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. |
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 | A spend limit (tenant or integration), the paid-concurrency limit or the per-operation cost cap was reached. | Wait for the window or raise the limit in the dashboard. |
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. |
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. |