Error codes
Every failure the API can produce is one of 54 codes. Each one has a page: what it means, what causes it, and whether retrying is worth anything.
On this page
The envelope#
Errors are served as application/problem+json and carry two views of the same failure. The nested error object is what this API has always returned and what your client should branch on. The sibling keys are RFC 9457 Problem Details, which generated SDKs, gateways and HTTP debuggers understand without a custom mapping.
{
"error": {
"code": "not_found",
"message": "Agent not found",
"request_id": "7cb7f7862a82425d8e4c3fb8a497dfe6"
},
"type": "https://integrable.cloud/docs/errors/not_found",
"title": "Not Found",
"status": 404,
"detail": "Agent not found",
"instance": "/api/agents/01a0652b-3713-7ea1-a6c9-2e895389ec34"
}Branch on error.code, never on the message. Codes are stable; messages are reworded whenever a clearer sentence is found. type is the permanent link to the page explaining a code — every one below resolves.
request_id. It is the only thing that lets us find the exact request in our logs, and on a 500 it is deliberately the only diagnostic the response carries — a traceback in a response body is a disclosure, not a courtesy.Authentication#
The key is missing, unverifiable, or not allowed to do this.
The request#
The shape of what was sent.
- 400bad_requestThe request could not be processed, and the reason does not fit a more specific code.
- 422validation_errorThe payload was well-formed JSON but failed schema validation.
- 405method_not_allowedThe path exists but does not accept this HTTP method.
- 415unsupported_media_typeThe `Content-Type` on the request is not one this endpoint reads.
- 413payload_too_largeThe uploaded body exceeds the limit for this endpoint.
- varieshttp_errorA generic fallback used when a failure has an HTTP status but no more specific code was assigned.
State and concurrency#
The resource is not where the request assumed it was.
- 404not_foundNo resource with that identifier exists in the workspace the key belongs to.
- 409conflictThe request contradicts the resource's current state.
- 428precondition_requiredSomething must happen before this request is allowed.
- 422idempotency_key_reusedThis `Idempotency-Key` was used before, for a request with a different body.
- 409idempotency_in_progressA request with this `Idempotency-Key` is running right now. The API is refusing to start a second one.
Limits and plan#
Too fast, or past what the plan allows. The two are different.
- 429rate_limitedToo many requests in the current window. The limit is per workspace, and some endpoints add a per-agent limit on top.
- 402quota_exceededYour plan's allowance for this resource is used up. This is a billing boundary, not a speed limit.
- 402plan_feature_requiredThe plan does not include this capability at all. Unlike a quota, nothing about it resets — only a different plan changes the answer.
The chat flow#
Raised by the public widget endpoints.
- 428lead_requiredThis agent is configured to collect visitor details before it will answer, and the required fields have not been supplied.
- 422challenge_failedThe agent-protection challenge on the public chat endpoint did not verify.
- 422handoff_disabledA visitor asked to be passed to a person, but this agent has no human handoff configured.
Talking to an agent#
Raised by the spoken widget endpoints, and by recording a business's own voice.
- 422no_speechThe recording held no speech the agent could hear, so there was nothing to answer.
- 413voice_too_longThe recording was longer than one spoken turn may be (about a minute), so it was not transcribed.
- 503voice_unavailableEvery service that turns speech into text, or a voice into speech, failed for this request.
- 403voice_offThis agent cannot be talked to: voice is switched off for it, or its plan does not include voice.
- 403voice_limitThe owner's limit on talking was reached - minutes in this conversation, or this agent's minutes this month.
- 409voice_ahead_missingThe turn named a transcript heard ahead during the visitor's pause, and it was not found - send the recording itself.
- 422voice_formatThe uploaded voice recording is not in a format the platform takes.
- 422voice_too_shortThe recording is too short to learn a voice from.
- 422voice_consent_requiredA business's own voice is stored only with the uploader's confirmation that it is their voice or that they have the speaker's permission.
- 422voice_consent_mismatchThe recording does not read the consent statement closely enough, so it was not stored and no voice was made from it.
Integrations#
Raised by a connected provider. The variants say whether retrying is worth anything.
- 502calendar_failedA calendar provider refused the request or did not answer.
- 401calendar_reauth_requiredThe stored calendar credential no longer works. The customer has to reconnect.
- 502destination_failedA lead destination — Sheets, HubSpot, a webhook — could not be reached.
- 502destination_auth_failedThe credential for this destination is gone. It must be reconnected.
- 502destination_not_configuredThis integration has no app credentials on this deployment. It is an operator problem, not yours.
- 502email_failedAn email could not be sent.
- 502email_transientThe send failed for a reason that may clear on its own.
- 502email_permanentThe send failed for a reason that will not change on a retry.
- 502email_not_configuredNo email provider credentials exist on this deployment.
- 502notification_failedA notification — WhatsApp, Telegram, Slack — could not be delivered.
- 502notification_transientDelivery failed for a reason worth retrying.
- 502notification_rejectedThe destination itself is wrong — that number or chat cannot receive the message.
- 502notification_not_configuredThis channel has no credentials on this deployment.
- 502payment_failedThe payment provider could not be reached.
- 502payment_transientA billing call failed for a reason that may clear.
- 400payment_permanentA billing call was rejected and retrying it will not help.
- 400payment_not_configuredBilling is not configured on this deployment.
- 401google_oauth_failedA Google sign-in could not be verified.
- 422flow_invalidA conversation flow failed validation and was not saved.
- 500decryption_failedStored data could not be decrypted. Nothing you sent caused this and nothing you send will fix it.
Ours, not yours#
Server-side failures. Quote the request id.
- 500internal_errorSomething failed on our side that was not anticipated. The response deliberately carries no detail beyond a request id.
- 500configuration_errorThe service is misconfigured for the operation you asked for. It is our fault, but it will not clear on its own.
- 502upstream_errorA service we depend on failed — a model provider, or an integration you have connected.
- 504upstream_timeoutA dependency accepted the request and then did not answer in time.
- 503service_unavailableThe API is temporarily not accepting this work.
Tool-call failures are a different thing#
If you are reading an audit row or a request log and see invalid_arguments, blocked, timeout, transport, too_large, misconfigured or budget_exhausted, those are not HTTP errors and have no pages here. They describe the outcome of a single tool call inside one agent turn, and they are recorded for metrics rather than returned to a caller. See Request logs.
Something unclear or missing? Tell us and we’ll fix it.