DocsError codes

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.

404 application/problem+json
{
  "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.

Always log 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 request#

State and concurrency#

Limits and plan#

The chat flow#

Talking to an agent#

Integrations#

Raised by a connected provider. The variants say whether retrying is worth anything.

Ours, not yours#

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.