{
"success": false,
"statusCode": 404,
"message": "Contact does not exist",
"code": "CONTACT_NOT_FOUND"
}
{
"success": false,
"statusCode": 400,
"message": "Validation failed",
"code": "INVALID_INPUT",
"errors": {
"email": "email should not be empty"
}
}
Authentication Errors
| Code | HTTP | Message | Resolution |
|---|---|---|---|
INVALID_API_KEY | 401 | Invalid or missing API key | Check that you’re sending a valid sk_live_* or sk_test_* key in the Authorization: Bearer header. |
FORBIDDEN | 403 | Insufficient permissions | Your API key doesn’t have access to this resource. |
Resource Errors
| Code | HTTP | Message | Resolution |
|---|---|---|---|
CONTACT_NOT_FOUND | 404 | Contact does not exist | Verify the contact ID. The contact may have been deleted in the connected CRM. |
LEAD_NOT_FOUND | 404 | Lead does not exist | Verify the lead ID. Not all providers support leads natively. |
MEETING_NOT_FOUND | 404 | Meeting does not exist | Verify the meeting ID. |
PROVIDER_NOT_FOUND | 404 | Provider does not exist | Check the provider slug. |
CONNECTION_NOT_FOUND | 404 | No active connection found | The end user hasn’t connected this provider. Use the Connect widget to establish a connection. |
END_USER_NOT_FOUND | 404 | End user does not exist | Verify the endUserId used when creating the connect token. |
CONNECTION_ALREADY_EXISTS | 409 | Connection already exists for this provider | An active connection already exists for this end user and provider. |
Validation Errors
| Code | HTTP | Message | Resolution |
|---|---|---|---|
INVALID_INPUT | 400 | Validation failed | Check the errors field for specific field-level failures. |
MISSING_REQUIRED | 400 | Required field is missing | Include all required fields in your request. |
MISSING_PROVIDER | 400 | Query parameter ?provider is required | Add ?provider=hubspot (or another slug) to your request URL. |
UNSUPPORTED_RESOURCE | 400 | Provider does not support this resource | Not all providers support all resources. |
INVALID_DATE_RANGE | 400 | End date must be after start | Ensure endDate is after startDate. |
INVALID_ISO_DATE | 400 | Query param must be ISO-8601 | The created_after / created_before filters must be in ISO-8601 format (e.g. 2026-05-11 or 2026-05-11T23:59:59Z). |
Method Not Allowed (405)
| Code | HTTP | Message | Resolution |
|---|---|---|---|
METHOD_NOT_ALLOWED | 405 | Operation <resource>.<op> is not supported by <provider> | The chosen provider doesn’t expose this operation for the resource. For example, financial reports (balance_sheet, income_statement, cash_flow_statement) and read-only resources (address, phone_number, general_ledger_transaction, transaction, bank_feed_account, bank_feed_transaction) only support list and get. company_info is update-only — it cannot be created or deleted. See the provider’s integration page for the full compatibility matrix. |
Provider Errors
These occur when communicating with the connected CRM or accounting provider.| Code | HTTP | Message | Resolution |
|---|---|---|---|
PROVIDER_ERROR | 502 | Provider returned an error | The provider returned an unexpected error. Retry the request. |
PROVIDER_RATE_LIMITED | 429 | Provider rate limit exceeded | The provider’s rate limit was hit. Respect the Retry-After header. |
PROVIDER_UNAVAILABLE | 503 | Provider is temporarily unavailable | The provider is down. Retry with exponential backoff. |
CIRCUIT_OPEN | 503 | Circuit breaker is open for this provider | Too many consecutive failures. Will auto-recover — retry after the indicated time. |
PROVIDER_AUTH_FAILED | 502 | Provider authentication failed | The user’s OAuth tokens are invalid. They need to reconnect via the Connect widget. |
NEEDS_REAUTH | 403 | Connection requires re-authentication | The OAuth token expired and couldn’t be refreshed. Prompt the user to reconnect. |
Server Errors
| Code | HTTP | Message | Resolution |
|---|---|---|---|
INTERNAL_ERROR | 500 | Something went wrong | Unexpected error. Retry the request. If persistent, contact support. |
SERVICE_UNAVAILABLE | 503 | Service temporarily unavailable | The platform is under maintenance. Retry with backoff. |
HTTP Status Code Summary
| Status | Meaning |
|---|---|
200 | OK — successful GET, PUT, PATCH, DELETE |
201 | Created — successful POST |
400 | Bad Request — validation error or missing parameter |
401 | Unauthorized — invalid or missing API key |
403 | Forbidden — connection needs re-auth |
404 | Not Found — resource doesn’t exist |
405 | Method Not Allowed — operation not supported by the chosen provider for this resource |
409 | Conflict — duplicate resource |
429 | Too Many Requests — rate limit exceeded |
500 | Internal Server Error |
502 | Bad Gateway — provider communication error |
503 | Service Unavailable — provider or platform down |