Responses and errors. One shape for every response.
Check ok first. A success has data; a failure has error with a stable code your code can switch on.
200success
{ "ok": true,
"data": { … },
"meta": { "requestId": "req_7c1…" } }403error
{ "ok": false,
"error": { "code": "insufficient_scope", … },
"meta": { "requestId": "req_9a4…" } }On this page
Success
{
"ok": true,
"data": { … },
"meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}dataholds the result. Each endpoint page lists its fields.- Lists also have
meta.pagination(see Pagination). - Every response has
meta.requestId, also sent as theX-Request-Idheader. Include it when you contact us about a request. - New fields may be added to any object. Your code should ignore fields it does not know; existing fields are never renamed or removed in v1.
Errors
{
"ok": false,
"error": {
"code": "insufficient_scope",
"message": "This token does not have the \"leads:read\" scope.",
"details": { "requiredScope": "leads:read" }
},
"meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}code is stable: use it in your code. message is for people and may change. details is only there when there is more to say, for example which field was wrong.
Error codes
| Status | Code | Meaning |
|---|---|---|
| 400 | validation_error | A field is missing or not valid. details names it. |
| 400 | invalid_body | The body is not JSON, or Content-Type: application/json is missing. |
| 401 | unauthorized | No token, or it is unknown, revoked or expired, or its creator left the account. |
| 403 | insufficient_scope | The token lacks the scope in details.requiredScope. |
| 403 | plan_required | The API needs the Growth plan or above. |
| 403 | subscription_inactive | The subscription is not active. |
| 403 | claimed_by_other | Another person on your team is handling this handover. |
| 404 | not_found | No such item, or the token may not see it (another account, or a chatbot the token is not limited to). |
| 405 | method_not_allowed | This path does not support that HTTP method. |
| 409 | already_handover, not_handover, already_resolved, not_resolved | The conversation is not in a state that allows this action. |
| 409 | not_ready, refresh_running | The knowledge source is still being processed. |
| 409 | idempotency_in_progress, idempotency_key_reused | See Retries and idempotency. |
| 413 | payload_too_large | The request body is over the limit. |
| 429 | rate_limited | Too many requests. Wait for the seconds in the Retry-After header. |
| 500 | internal_error | Something failed on our side. Retry later; send us the requestId if it persists. |
| 503 | lock_failed | A short conflict while claiming a handover. Retry the request. |
The errors listed on each endpoint page are the ones specific to it. Any endpoint can also return 401, 403 (insufficient_scope, plan_required, subscription_inactive), 413, 429 and 500.