> ## Documentation Index > Fetch the complete documentation index at: https://docs.stateset.com/llms.txt > Use this file to discover all available pages before exploring further. # Errors across the engines > Every engine returns a machine-readable error body — but not the same one. The shapes, side by side, and what an agent should do with each. Twelve API surfaces, several codebases, several error envelopes. Each engine's pages list its own status codes; this page is the cross-reference — read it once and your error handler (or your agent's) will know what to parse everywhere. ## The shapes | Engine | Error body | The machine-readable part | | ---------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Commerce Engine](/api-reference/commerce/overview) | `{ "error": { "code", "message", "invariant"? } }` | `error.invariant` — a stable [commerce invariant code](/api-reference/commerce/invariant-codes) when a business rule was violated; `error.code` otherwise | | [ResponseCX](/api-reference/responsecx/overview) | `{ "error", "code" }` (400s add `issues` naming the fields) | `code`, e.g. `agent_not_found`, `eval_not_found` | | [Voice](/api-reference/voice/overview) | `{ "ok": false, "error" }` | `ok` is the discriminator; `error` is the message | | [Chat Widget](/api-reference/chat-widget/overview) | `{ "error", "type"? }` | `type`; the widget shows `error` inline and calls `onError` | | [Sync Server](/api-reference/sync/overview) | `{ "meta": { "requestId" }, "error": { "code", "message", "details"? } }` | `error.code`; keep `meta.requestId` for support | | [Temporal Engine](/api-reference/temporal/overview) | `{ "error", "message", "details"? }` | `error`, e.g. `IDEMPOTENCY_CONFLICT` on a replayed start with a different payload | | [EDI](/api-reference/edi/overview) | `{ "success": false, "error": { "code", "message" } }` | `error.code`: `x12_parse_error`, `validation_error`, `not_found`, `duplicate_interchange`, `unauthorized`, `forbidden`, `rate_limited`, `upstream_error`, or an internal `*_error`. 5xx messages are deliberately generic — quote the correlation ID | | [NSR](/api-reference/nsr/overview) | `{ "code", "message" }` | `code`, e.g. `not_found`, `bad_request` — and remember a `refused` **decision** is a 200, not an error | | [Computer Use](/api-reference/computer-use/overview) | `{ "detail" }` (FastAPI; 422 carries a list of field locations) | `detail` | | [Agents](/api-reference/agents/overview) | `{ "error": { "code", "message", "details" }, "request_id", "timestamp", "path" }` | `error.code`; `request_id` for correlation | | [Sandbox](/stateset-sandbox/stateset-sandboxes) | `{ "error" }` | the message | ## The five situations that matter However the envelope is spelled, an error lands in one of five families. This is the branch table an agent needs: | Family | Typical codes | What to do | | --------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Your request is malformed** (400/422) | `validation_error`, `bad_request`, FastAPI `detail[]`, ResponseCX `issues` | Fix the named field and retry once. Do not retry unchanged | | **Your credential is wrong** (401/403) | `unauthorized`, `forbidden` | Check the header *name* first — each engine reads its own ([router](/api-reference/introduction#hosts-keys-headers)) — then the key's scope. Never retry in a loop | | **The thing is missing** (404) | `not_found`, `agent_not_found` | Treat as data, not failure: create it, or surface "no such order" | | **You already did this** (409) | `duplicate_interchange`, `IDEMPOTENCY_CONFLICT` | Success in disguise when you sent the same `Idempotency-Key` with the same payload; a real bug when the payload differs | | **The engine is struggling** (429/5xx) | `rate_limited`, `upstream_error`, generic 5xx | Back off and retry with the **same** `Idempotency-Key`. Keep `requestId` / `request_id` / correlation ID for support | **Business refusals are not transport errors.** The Commerce Engine rejects an illegal state transition with a 4xx carrying an `invariant` code an agent can branch on; NSR answers a refused authorization with a **200** whose verdict is `refused` (with the cited rules); a Voice call blocked by DNC or quiet hours is a policy `403`. Handle these as decisions, not retries. ## Related * [API Reference router](/api-reference/introduction) — hosts, headers and env vars per engine * [Commerce invariant codes](/api-reference/commerce/invariant-codes) — the 24 stable `commerce.*` codes * [Host status](/api-reference/hosts) — when a 5xx means "provisioning", the table says so