Error catalog
All errors arrive as application/problem+json (RFC 9457). Branch on the code field, not on the detail text. The type field of every error links to this page.
Access and key
| Code | HTTP | Title | When it occurs | What to do |
|---|---|---|---|---|
integration_inactive | 401 | Integration is not active | The integration is suspended or revoked, or its owner lost access. The key itself is fine. | Check the integration in the dashboard (Settings → API). |
invalid_api_key | 401 | Invalid API key | The header is missing, or the key is unknown, revoked or expired. The response is deliberately identical in all cases: the platform does not confirm that such a key ever existed. | Check the key; its expiry is visible in GET /me (key.expires_at). Issue a new one if needed. Do not retry automatically. |
wrong_cell | 401 | Key belongs to another cell | The key was issued in another cell. The response carries the correct_base_url field. | Use the base URL from correct_base_url. |
feature_not_in_plan | 403 | API is not included in the plan | The licence or plan does not include the API (api_access) or the specific feature. | Change the plan or contact support. |
ip_not_allowed | 403 | IP address is not allowed | The request came from an address outside the integration allowlist. | Add the address to the list or call from an allowed one. |
pii_transfer_not_allowed | 403 | Personal data transfer is not allowed | Cell RU: a scope with personal data was requested, but the IP allowlist or the recipient country does not permit the transfer. | Host the receiving system in Russia, set an IP allowlist, or do not request personal-data scopes. |
scope_missing | 403 | Scope is missing | A required scope is missing, or it was cut by the integration role, the owner permissions or the plan. | Check the scopes in GET /me (key.scopes) and the owner permissions. |
tenant_inactive | 403 | Account is not active | The tenant account is not active. | Contact support. |
Request
| Code | HTTP | Title | When it occurs | What to do |
|---|---|---|---|---|
bad_request | 400 | Bad request | The body is not JSON, or the Content-Type or a header is invalid. | Fix the request; a retry without changes is pointless. |
idempotency_key_required | 400 | Idempotency-Key header is required | The Idempotency-Key header is required for this request. | Add the header with a value unique per operation. |
not_found | 404 | Not found | The resource does not exist or belongs to another tenant (the same thing for a client). | Check the identifier. |
method_not_allowed | 405 | Method not allowed | The method is not supported at this URL. | Check the reference. |
channel_not_configured | 409 | Integration channel is not configured | The integration has no api channel, so there is nowhere to create conversations or accept customer messages. Connect the channel in the dashboard (Settings → API → “Connect chat channel”). | Connect the channel in the dashboard; channel_id is visible in GET /me. Retrying without it is pointless. |
encryption_key_required | 409 | Encryption key is required | The integration is set to return personal-data fields only in JWE format (mode required), but no recipient public key is registered. Happens on the EN and ID cells only. | Register your public key (PUT /me/encryption-key or the dashboard), or request fields without personal data via fields=. |
idempotency_conflict | 409 | Idempotency key was used with a different request | The Idempotency-Key was already used with a different request body. | Use a new key for a new request or repeat the original request. |
invalid_state | 409 | Invalid state | The action is not allowed in the current state of the resource. | Re-read the resource and check its state. |
operation_in_progress | 409 | Operation is in progress | A parallel retry: the operation with this Idempotency-Key is still running. | Wait for Retry-After or poll the operation. |
precondition_failed | 412 | Precondition failed | If-Match does not match the current version: the resource was modified. | Re-read the resource and apply the change to the current version. |
payload_too_large | 413 | Payload too large | The request body is larger than 256 KB. | Make the body smaller. |
validation_failed | 422 | Validation failed | Parameters failed validation; details are in errors[]. | Fix the request following errors[]. |
precondition_required | 428 | Precondition required | If-Match was not sent for the modification. | Send the version from the last read. |
Money and limits
| Code | HTTP | Title | When it occurs | What to do |
|---|---|---|---|---|
insufficient_funds | 402 | Insufficient funds | The wallet does not hold enough funds for a paid operation. | Top up the wallet. |
spend_limit_reached | 402 | Spend limit reached | The integration daily spend limit was reached (the day is counted in the cell time zone), or the estimated cost of the operation exceeds the per-operation cap (100 in the wallet currency by default). The concurrency limit is a separate code, concurrency_limit (429). | Wait for the next day or raise the limit; for the per-operation cap, pick a cheaper model for the agent or lower max_tokens. The limit and the spend are in GET /me (wallet.daily_spend, limits.max_operation_cost). |
wallet_suspended | 402 | Wallet is suspended | Data exchange is suspended: the tenant wallet balance is negative or the wallet is blocked. Every route except GET /me and GET /wallet answers 402; incoming data (events, messages, leads) is not accepted and outgoing webhooks are postponed. The response carries topup_url and balance. | Top up the wallet at topup_url (a staff member with the top-up permission must sign in). Exchange resumes by itself within 30 seconds of the credit; the state is visible in GET /wallet. Events are not lost: webhooks are delivered after the top-up. |
concurrency_limit | 429 | Too many concurrent operations | The integration already runs the maximum number of concurrent paid operations (5 by default; see GET /me, limits.paid_concurrency). | Wait for Retry-After or for running operations to finish and retry with the same Idempotency-Key. Queue the messages on your side. |
rate_limited | 429 | Too many requests | The request rate limit was exceeded. | Wait Retry-After seconds and retry with the same Idempotency-Key. |
Platform
| Code | HTTP | Title | When it occurs | What to do |
|---|---|---|---|---|
internal_error | 500 | Internal error | An internal platform error. No details are disclosed in the response. | Retry with a pause; if it persists, send the request_id to support. |
service_unavailable | 503 | Service unavailable | The limits store or the database is unavailable, or the API is not enabled on the cell: a write cannot be accepted safely. | Retry with a pause and the same Idempotency-Key. |
upstream_unavailable | 503 | Upstream service unavailable | An external dependency, such as a language model, is unavailable. | Retry with a pause and the same Idempotency-Key. |