Errors

Every error response from /v1 follows the same envelope. This page lists the HTTP statuses, the stable error codes, and what to do about each.

The error envelope

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key.",
    "requestId": "req_abc..."
  }
}

The requestId correlates the request with our logs. Include it when filing a support ticket.

Status	Cause	What to do
`400`	Malformed request (e.g. invalid JSON).	Check the body against the API reference.
`401`	Missing or invalid API key.	Send `Authorization: Bearer <key>`.
`404`	Resource not found, or outside your organization.	Verify the actor id; contact support if you expected access.
`422`	Input failed schema validation.	Inspect the response `message`; it names the offending field path.
`500`	Bug on our side.	Retry with exponential backoff; include `requestId` if persistent.

Stable identifiers on error.code.

Code	HTTP	Meaning	Recovery
`unauthorized`	401	Auth failed or missing.	Verify the `Authorization: Bearer qk_live_...` header.
`bad_request`	400	Body malformed (not JSON, etc.).	Check the body and `Content-Type` header.
`not_found`	404	Resource does not exist or is outside your organization.	Verify the actor id; contact support if you expected access.
`unprocessable_entity`	422	Input failed schema validation.	Inspect `message` for the offending field path.
`internal_server_error`	500	Bug on our side.	Retry with backoff; include `requestId` if persistent.

Idempotency is documented on the API reference and on the actors concept page.

API reference. Authentication, base URL, and idempotency.
SDK errors and retries. The { data, error, response } model and a retry helper.