Error codes

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": "Bot not found",
    "request_id": "7cb7f7862a82425d8e4c3fb8a497dfe6"
  },
  "type": "https://integrable.cloud/docs/errors/not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Bot not found",
  "instance": "/api/bots/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.

The key is missing, unverifiable, or not allowed to do this.

• 401unauthenticatedThe request carried no API key, or one the API could not verify.
• 403forbiddenThe key is valid, but it is not allowed to do this — either the scope is missing or the resource belongs to another workspace.

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.

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.

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-bot 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.

Raised by the public widget endpoints.

• 428lead_requiredThis bot is configured to collect visitor details before it will answer, and the required fields have not been supplied.
• 422challenge_failedThe bot-protection challenge on the public chat endpoint did not verify.
• 422handoff_disabledA visitor asked to be passed to a person, but this bot has no human handoff configured.

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.

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.

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 assistant turn, and they are recorded for metrics rather than returned to a caller. See Request logs.