Errors

Every non-2xx response includes one error object.

The error envelope

{
  "error": {
    "type": "invalid_request",
    "code": "transport.type.missing",
    "message": "Field `transport.type` is required.",
    "param": "transport.type",
    "request_id": "req_01HYZ..."
  }
}

Field	Type	Notes
`type`	string	Broad, stable failure category. Not always one-to-one with HTTP status. See the table below.
`code`	string	Stable, machine-readable subcode in `lower_snake_case` / dotted form.
`message`	string	Human-readable. May change, so don’t parse it.
`param`	string \| null	The offending request field (dot-path), when applicable.
`request_id`	string	`req_...`; include this when contacting support. Also echoed in `X-Request-Id`.

Error types

error.type is one of a fixed set:

HTTP	`error.type`	When it happens
400	`invalid_request`	Malformed JSON, missing or invalid field.
401	`authentication`	Missing, bad, or revoked API key.
402	`quota_exceeded`	Not enough credits, or billing isn’t active for a credit-gated action.
403	`permission`	Authenticated, but the key can’t access this resource.
404	`not_found`	Resource doesn’t exist (or isn’t in your scope).
409	`conflict`	Idempotency conflict or a state-machine clash.
422	`unprocessable`	Request shape is fine but the semantics are invalid.
429	`rate_limit`	Per-key rate limit exceeded.
429	`quota_exceeded`	Per-org concurrency or usage quota exhausted.
500	`internal`	Unexpected server error.
503	`service_unavailable`	No capacity, or scheduled maintenance.

Two cases share 429: rate_limit means you’re calling too fast (back off and retry), while quota_exceeded means a plan ceiling like concurrent sessions is full (retrying won’t help until capacity frees up). Branch on error.type to tell them apart.

Rate limits and retries

429 and 503 responses may include Retry-After in seconds. Use that delay before retrying.

Quota exhaustion

A quota_exceeded error names the exhausted resource in error.code. Credit exhaustion uses HTTP 402 with code: "insufficient_credit_balance". Runtime limits, such as concurrent sessions, use HTTP 429.

{
  "error": {
    "type": "quota_exceeded",
    "code": "concurrent_sessions",
    "message": "Org org_... already has 5 concurrent sessions (max 5).",
    "param": null,
    "request_id": "req_..."
  }
}

Handling errors

For API integrations, use the HTTP status and error.code for control flow. error.message is written for humans and may change.

Quotas

Session caps, usage rounding, and credit behavior.

API Reference

Endpoint schema generated from OpenAPI.

Get started

Integrations

Guides

Reference

The error envelope

Error types

Rate limits and retries

Quota exhaustion

Handling errors

Next

Quotas

API Reference

​The error envelope

​Error types

​Rate limits and retries

​Quota exhaustion

​Handling errors

​Next

Quotas

API Reference

The error envelope

Error types

Rate limits and retries

Quota exhaustion

Handling errors

Next