StateSet API Docs

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	`{ "error": { "code", "message", "invariant"? } }`	`error.invariant` — a stable commerce invariant code when a business rule was violated; `error.code` otherwise
ResponseCX	`{ "error", "code" }` (400s add `issues` naming the fields)	`code`, e.g. `agent_not_found`, `eval_not_found`
Voice	`{ "ok": false, "error" }`	`ok` is the discriminator; `error` is the message
Chat Widget	`{ "error", "type"? }`	`type`; the widget shows `error` inline and calls `onError`
Sync Server	`{ "meta": { "requestId" }, "error": { "code", "message", "details"? } }`	`error.code`; keep `meta.requestId` for support
Temporal Engine	`{ "error", "message", "details"? }`	`error`, e.g. `IDEMPOTENCY_CONFLICT` on a replayed start with a different payload
EDI	`{ "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	`{ "code", "message" }`	`code`, e.g. `not_found`, `bad_request` — and remember a `refused` decision is a 200, not an error
Computer Use	`{ "detail" }` (FastAPI; 422 carries a list of field locations)	`detail`
Agents	`{ "error": { "code", "message", "details" }, "request_id", "timestamp", "path" }`	`error.code`; `request_id` for correlation
Sandbox	`{ "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) — 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.

API Reference router — hosts, headers and env vars per engine
Commerce invariant codes — the 24 stable commerce.* codes
Host status — when a 5xx means “provisioning”, the table says so

Last modified on August 31, 2026

Get started

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Errors across the engines

The shapes

The five situations that matter

​The shapes

​The five situations that matter

​Related

The shapes

The five situations that matter

Related