Errors

Business errors returned by the API use this shape:

{
  "code": "state_version_conflict",
  "message": "The session changed since it was last read.",
  "request_id": "req_01J8...",
  "details": {
    "current_state_version": 4
  }
}

Field	Purpose
`code`	Stable machine-readable identifier. Branch on this value.
`message`	Human-readable summary, not a stable programmatic contract.
`request_id`	Correlation identifier to include in support requests.
`details`	Optional structured context specific to the error.

Common status codes

Status	Common codes	Recommended action
`401`	`unauthorized` (when returned by the application)	Check authentication.
`403`	Gateway denial; a JSON envelope is not guaranteed	Check the key (missing, invalid, expired, or revoked), domain, and scope; do not assume every `403` has `insufficient_scope`.
`404`	`unknown_session`, `unknown_configuration`, `unknown_compilation`	Check the identifier and domain attached to the key.
`409`	`state_version_conflict`, `idempotency_key_reused`, `compilation_in_progress`	Read current state or use a new idempotency key, depending on the code.
`410`	`compiled_artifact_unavailable`	Create a new session on an available configuration.
`422`	`invalid_previous_turn`, `invalid_choice`, `constraint_no_match`, `configuration_validation_failed`	Correct the payload or configuration.
`429`	usage limit	Wait as directed by response headers and use backoff with jitter.
`503`	`idempotency_contention`	Retry briefly with the same intent and bounded backoff.

Log the request_id, endpoint, status, and code, but never the Authorization header or unnecessary visitor text.

An invalid key is rejected before the business API. The gateway may return 403 without code, details, or request_id in the body. Parse the envelope above only when the response actually contains it.

degraded: true in a successful response is not an HTTP error. The decision remains usable; inspect degraded_reasons for observability.

API guides

Sessions

Configuration

Service

Common status codes