Errors

The API uses conventional HTTP status codes and returns exactly one JSON error envelope on every failure. Inspect error.code for programmatic handling; error.message is human-readable and may change.

Error envelope

{
  "error": {
    "type": "invalid_request",
    "code": "window_unavailable",
    "message": "The selected model does not support the 'loose' completion window.",
    "request_id": "req_01H8XK2M...",
    "param": "window"
  }
}

string

Coarse class tied to the HTTP status (see below). SDKs subclass their exception types on type.

string

Stable, machine-branchable string. Switch on this — it is the one taxonomy that never changes meaning.

string

Human-readable explanation. Do not parse.

string

The id of the failing request (matches the x-request-id response header). Quote it in support requests.

string | null

The request field that caused the error, when the failure is attributable to one.

request_id is returned on every response — success and error — via the x-request-id header. On errors it is also mirrored inside the envelope. See the overview.

Types

type is the coarse class and maps one-to-one onto the HTTP status. SDKs subclass their exception hierarchy on it.

Type	HTTP
`invalid_request`	400
`authentication`	401
`quota`	402
`permission`	403
`not_found`	404
`conflict`	409
`rate_limit`	429
`api_error`	500
`not_implemented`	501

Codes

code is the stable, machine-branchable string. Branch on it; it never changes meaning across versions.

Code	Type	HTTP	Meaning
`validation_failed`	`invalid_request`	400	The request was malformed or failed validation.
`window_unavailable`	`invalid_request`	400	The model does not support the requested completion window.
`unauthorized`	`authentication`	401	Missing or invalid API key.
`budget_exceeded`	`quota`	402	The call would breach an agent/session/org budget.
`insufficient_credits`	`quota`	402	The org’s credit balance is too low to cover the call.
`subscription_required`	`quota`	402	The org holds no active plan. Start or renew it with `POST /v1/credits/subscription`.
`forbidden`	`permission`	403	The key or member lacks the required scope/role, or a permission policy denied the action.
`not_found`	`not_found`	404	The resource does not exist in this organization.
`version_conflict`	`conflict`	409	Optimistic-concurrency mismatch on an agent update: the `expected_version` is stale.
`revision_conflict`	`conflict`	409	A shared declaration moved underneath an apply: the install’s `revision` is not the `expected_revision` you sent. The message names the paths that drifted.
`name_conflict`	`conflict`	409	The name is held by a resource another `project` owns, and the request did not ask to `adopt` it. See Apps.
`idempotency_conflict`	`conflict`	409	An `Idempotency-Key` was replayed with a different body. See the overview.
`session_running`	`conflict`	409	Input was sent to a running session without `interrupt`.
`session_terminal`	`conflict`	409	The session has already ended and cannot accept input.
`computer_unavailable`	`conflict`	409	The requested computer is not ready or has failed.
`job_not_ready`	`conflict`	409	Nothing is wrong — the work is not ready yet. Retry.
`compliance_pending`	`conflict`	409	The action waits on a verification or carrier approval that has not cleared. Retry later.
`rate_limited`	`rate_limit`	429	Too many requests; back off and retry after `Retry-After`.
`internal_error`	`api_error`	500	Something failed on our side. Retry with backoff; the `request_id` is what to quote.
`feature_not_configured`	`not_implemented`	501	The feature is recognized but not configured for this organization.

version_conflict is a returned error: agent updates use optimistic concurrency, so a stale expected_version fails with 409. Refetch current_version and re-apply your change.

The four `409`s are four different remedies

A 409 is not one thing, and the code is what tells you which. version_conflict means one versioned object is stale — re-read it and re-apply. revision_conflict means a whole shared declaration moved — merge, using the paths the message names. name_conflict means somebody else owns the name — pick another or adopt. job_not_ready and compliance_pending mean nothing is wrong at all — retry, and a client that treats them as terminal gives up on work that was going to succeed.

Handling errors

Retry 429 and transient 5xx responses with exponential backoff, honoring Retry-After on 429. Treat 400, 401, 402, 403, and 404 as terminal — fix the request or credentials rather than retrying. Branch a 409 on its code, never on the status — two of them are retryable and the rest are not.

const res = await fetch(url, options);
if (!res.ok) {
  const { error } = await res.json();
  switch (error.code) {
    case "version_conflict": // refetch current_version and retry
    case "revision_conflict": // the declaration moved: merge on error.message's paths, re-apply
    case "name_conflict":    // another project owns the name: rename, or re-send with adopt
    case "job_not_ready":    // not an error — back off and retry
    case "compliance_pending": // not an error — retry once verification clears
    case "rate_limited":     // back off and honor Retry-After
    case "subscription_required": // send the customer to POST /v1/credits/subscription
    case "insufficient_credits": // top up credits, then retry
    case "budget_exceeded":  // raise the cap or top up credits
    default:                 // surface error.message + error.request_id
  }
}

Every mutation accepts an Idempotency-Key, so retrying a request that failed with a network error or 429 will not double-apply. See the overview.

Introduction

Core resources

Platform

Identity

Error envelope

Types

Codes

The four `409`s are four different remedies

Handling errors

​Error envelope

​Types

​Codes

​The four 409s are four different remedies

​Handling errors

Error envelope

Types

Codes

The four `409`s are four different remedies

Handling errors