Errors - Clarity Support Docs

Error bodies

The two APIs shape errors differently.

Voice API
Support API

A JSON object with an error field. Many errors add a machine-readable code or a human message. A body that fails validation returns 422 with an issues list, one entry per problem, each with the field path, a code, and a message.

{ "error": "publish_capability_required", "code": "PUBLISH_CAPABILITY_REQUIRED" }

Match on code when it is present, and on error otherwise. Don’t match on message; its wording can change.

A JSON object with a stable code, a human message, and optional extra details.

{ "status": "error", "code": "ticket_not_found", "message": "Ticket not found", "extra": null }

Match on code. A request that fails validation returns 400 with code bad_request and the failing fields listed in extra.

Status codes

Status	Meaning	What to do
`400`	The request is malformed, fails validation (Support API), or breaks a rule of the endpoint.	Read the error body; it names the problem.
`401`	No key, or the key is unknown, expired, or revoked.	Check the `Authorization: Bearer <key>` header. See Authentication.
`403`	The key can’t do this: the action needs a signed-in person, or the resource belongs to another organization.	Use the Clarity app for live-call controls, and check the ids.
`404`	Unknown id, or an id from another project or organization.	Check the path and the ids.
`409`	The resource isn’t in a state that allows the action, for example dispatching a call to an agent that has never been published.	Read the error body, fix the state (publish the agent, finish the running campaign), and retry.
`422`	Validation failed (Voice API), including publishing an agent whose configuration is invalid.	Fix the fields the body names.
`429`	Too many requests.	Back off and retry later.
`5xx`	A failure on Clarity’s side or in a provider it calls.	Retry with backoff. If it persists, contact hello@onclarity.com with the time of the request.