Reference

Errors

The response envelope, HTTP status codes, app-specific error codes, and what to retry.

Envelope

Every JSON response includes success. Failures add message, and some add a machine-readable code:

{ "success": false, "code": "MODULE_DISABLED", "message": "chat is disabled for this site" }

Treat message as text for logs and support, and branch on the HTTP status (and code where present).

Status	Meaning	Action
`200`	Success; for POSTs with an `Idempotency-Key`, a replay (`duplicate: true`)	Use the returned id
`201`	Created	Use the returned id
`400`	Request rejected — missing or invalid fields	Fix the request; do not retry unchanged
`401`	Missing, unknown or revoked key	Check the header and the current key
`403`	Key belongs to another app, site disabled, origin not allowed, module off, or browser CORS	Fix configuration; do not retry unchanged
`404`	Resource not found (e.g. a conversation with the wrong visitor token)	—
`409`	`Idempotency-Key` reused with different content	Generate a new key for the new content
`429`	Rate limit	Wait for `RateLimit-Reset` seconds, then retry
`503`	Temporary: key verification or the assistant unavailable	Retry with exponential backoff
`5xx`	Unexpected failure	Retry with backoff; if it persists, contact support with the time and endpoint

Code	App	Status	Meaning
`CORS_ORIGIN_DENIED`	Form Capture	403	The request came from a browser origin. Call from a server.
`MODULE_DISABLED`	AI Chat · Managed Forms · Support Desk	403	That module is off for the site.
`IDENTITY_REQUIRED`	AI Chat	400	The site requires a visitor email before chatting.
`CHAT_FAILED`	AI Chat	4xx / 5xx	Generic chat failure; see `message`.
`ASSISTANT_UNAVAILABLE`	AI Chat	503	The model did not answer. The visitor's message was kept; retry later.

Form Capture errors carry a message only; the responses table lists every one.

Retry 429, 503 and network errors — with the same Idempotency-Key so a retry can never duplicate a record.
Do not retry 400, 401, 403 or 409 without changing the request.
Use exponential backoff starting at one second, capped around a minute, and give up after a handful of attempts with the record queued on your side.