Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Understand the uniform V1 error envelope and safe retry behavior.
{
"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. |
| Status | Common codes | Recommended action |
|---|---|---|
401 | unauthorized | Check or replace the key. |
403 | insufficient_scope | Use a key with the required scope. |
404 | unknown_session, unknown_configuration, unknown_compilation | Check the identifier and NBQ 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. |
request_id, endpoint, status, and code, but never the Authorization header or unnecessary visitor text.degraded: true in a successful response is not an HTTP error. The decision remains usable; inspect degraded_reasons for observability.