> ## Documentation Index
> Fetch the complete documentation index at: https://docs.support.onclarity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error bodies each API returns, the status codes, and what to do about them.

## Error bodies

The two APIs shape errors differently.

**Voice 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`.

```json theme={null}
{ "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.

**Support API**

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

```json theme={null}
{ "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](/authentication.md). |
| `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](mailto:hello@onclarity.com) with the time of the request. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.