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

# Errors

> What every status code means, and what to do about it.

## Error format

Errors always have a `message`. Many also have a `code`: a stable identifier you can match in your code. Match on `code`, never on the wording of `message`.

```json
{
  "code": "participant_not_found",
  "message": "No customer has that id."
}
```

A validation error (`400`) lists everything to fix:

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": ["email must be an email", "name should not be empty"]
}
```

## Status codes

| Status | Meaning | What to do |
| - | - | - |
| `200` | Success, or an idempotent repeat. | |
| `201` | Created. | |
| `400` | The request is not valid. | Fix it. Do not retry unchanged. |
| `401` | Key missing or not valid. | Check the `Authorization` header and that the key is not revoked. |
| `403` | The key lacks the scope. | Use a key with the [scope](/authentication.md#scopes) the endpoint needs. |
| `404` | Nothing has that id. | Check the id. |
| `409` | Conflicts with existing data. | See the `code`. |
| `413` | The request body is larger than 1 MB. | Send less. |
| `422` | Understood, but not allowed. | See the `code`. |
| `429` | Too many requests. | Wait for `Retry-After`. See [Rate limits](/guides/rate-limits.md). |
| `5xx` | Something went wrong on our side. | Retry with backoff. |

## Error codes

| Code | Status | Meaning |
| - | - | - |
| `participant_not_found` | `404` | No customer has that id. |
| `thread_not_found` | `404` | No conversation has that id. |
| `message_not_found` | `404` | No message has that id, for example as `before`. |
| `participant_conflict` | `409` | The `externalId` and the `email` belong to different customers. |
| `email_in_use` | `409` | Another customer already uses that email. |
| `contact_blocked` | `422` | The customer is blocked and cannot start conversations. |
| `nothing_to_update` | `400` | A customer update had no fields to change. |
| `unknown_attribute` | `400` | An attribute you sent does not exist. |
| `invalid_attributes` | `400` | An attribute value is not valid. |
| `invalid_tag` | `400` | A tag is not valid. |

## Which errors to retry

> [card] Retry
>
> Network errors and timeouts, `429`, and `5xx`. Use exponential backoff with jitter, and honour `Retry-After`. Send an [idempotency key](/guides/idempotency.md) on writes.

> [card] Do not retry
>
> `400`, `401`, `403`, `404`, `409` and `422`. The same request will fail the same way.
