Skip to main content

​
Error Codes

All API errors follow a consistent format: 
{
  "success": false,
  "statusCode": 404,
  "message": "Contact does not exist",
  "code": "CONTACT_NOT_FOUND"
}
Validation errors include field-level details: 
{
  "success": false,
  "statusCode": 400,
  "message": "Validation failed",
  "code": "INVALID_INPUT",
  "errors": {
    "email": "email should not be empty"
  }
}

​
Authentication Errors

CodeHTTPMessageResolution
INVALID_API_KEY401Invalid or missing API keyCheck that you’re sending a valid sk_live_* or sk_test_* key in the Authorization: Bearer header.
FORBIDDEN403Insufficient permissionsYour API key doesn’t have access to this resource.

​
Resource Errors

CodeHTTPMessageResolution
CONTACT_NOT_FOUND404Contact does not existVerify the contact ID. The contact may have been deleted in the connected CRM.
LEAD_NOT_FOUND404Lead does not existVerify the lead ID. Not all providers support leads natively.
MEETING_NOT_FOUND404Meeting does not existVerify the meeting ID.
PROVIDER_NOT_FOUND404Provider does not existCheck the provider slug.
CONNECTION_NOT_FOUND404No active connection foundThe end user hasn’t connected this provider. Use the Connect widget to establish a connection.
END_USER_NOT_FOUND404End user does not existVerify the endUserId used when creating the connect token.
CONNECTION_ALREADY_EXISTS409Connection already exists for this providerAn active connection already exists for this end user and provider.

​
Validation Errors

CodeHTTPMessageResolution
INVALID_INPUT400Validation failedCheck the errors field for specific field-level failures.
MISSING_REQUIRED400Required field is missingInclude all required fields in your request.
MISSING_PROVIDER400Query parameter ?provider is requiredAdd ?provider=hubspot (or another slug) to your request URL.
UNSUPPORTED_RESOURCE400Provider does not support this resourceNot all providers support all resources.
INVALID_DATE_RANGE400End date must be after startEnsure endDate is after startDate.

​
Provider Errors

These occur when communicating with the connected CRM/PMS.
CodeHTTPMessageResolution
PROVIDER_ERROR502Provider returned an errorThe CRM returned an unexpected error. Retry the request.
PROVIDER_RATE_LIMITED429Provider rate limit exceededThe CRM’s rate limit was hit. Respect the Retry-After header.
PROVIDER_UNAVAILABLE503Provider is temporarily unavailableThe CRM is down. Retry with exponential backoff.
CIRCUIT_OPEN503Circuit breaker is open for this providerToo many consecutive failures. Will auto-recover — retry after the indicated time.
PROVIDER_AUTH_FAILED502Provider authentication failedThe user’s OAuth tokens are invalid. They need to reconnect via the Connect widget.
NEEDS_REAUTH403Connection requires re-authenticationThe OAuth token expired and couldn’t be refreshed. Prompt the user to reconnect.

​
Server Errors

CodeHTTPMessageResolution
INTERNAL_ERROR500Something went wrongUnexpected error. Retry the request. If persistent, contact support.
SERVICE_UNAVAILABLE503Service temporarily unavailableThe platform is under maintenance. Retry with backoff.

​
HTTP Status Code Summary

StatusMeaning
200OK — successful GET, PATCH, DELETE
201Created — successful POST
400Bad Request — validation error or missing parameter
401Unauthorized — invalid or missing API key
403Forbidden — connection needs re-auth
404Not Found — resource doesn’t exist
409Conflict — duplicate resource
429Too Many Requests — rate limit exceeded
500Internal Server Error
502Bad Gateway — provider communication error
503Service Unavailable — provider or platform down