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

# Errors

> Response codes, the shape of an error, and what to do about each one.

An error always answers in JSON with at least a readable `message`. Messages are in the installation's default language: rely on the HTTP code and the field names, not on the text.

## The codes

| Code        | Means                                                                                                 | What to do                                        |
| ----------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `200` `201` | Done, or created.                                                                                     |                                                   |
| `202`       | Accepted and queued: the work happens in the background (an import, a large batch).                   | Follow the `url` in the answer.                   |
| `204`       | Deleted. No body.                                                                                     |                                                   |
| `400`       | Malformed request (an idempotency key that is too long…).                                             | Fix the call.                                     |
| `401`       | No token, or a revoked one.                                                                           | Check the `Authorization` header.                 |
| `403`       | Ability, role or team not enough, or the team is suspended.                                           | Read `message`.                                   |
| `404`       | Nothing of that name in this team.                                                                    | Check the `id`.                                   |
| `409`       | Conflict: a campaign being sent, someone already in the automation, an idempotent call still running. | Read `message`; do not send it again as is.       |
| `422`       | The data was refused.                                                                                 | Read `errors` or `message`.                       |
| `429`       | Too many calls.                                                                                       | Wait `Retry-After` seconds.                       |
| `502`       | A transactional e-mail refused by the sending provider.                                               | The detail is in `failure_reason`.                |
| `5xx`       | Lekalao's own problem.                                                                                | Try again later, with the same `Idempotency-Key`. |

## Validation errors

`422` with the detail field by field:

```json theme={null}
{
    "message": "The email field must be a valid email address.",
    "errors": {
        "email": ["The email field must be a valid email address."],
        "tags.2": ["The tags.2 field must not be greater than 255 characters."]
    }
}
```

Fields inside arrays are named by their position: `subscribers.14.email` is the 15th line of a batch.

## Refusals that are not about the data

Some `422` answers carry only a `message`, because the data is valid but the operation is not possible:

| Message                                                      | Situation                                                       |
| ------------------------------------------------------------ | --------------------------------------------------------------- |
| "This address is blocked."                                   | The address is on the suppression list.                         |
| "Your plan holds 3 subscribers. Move up a plan to add more." | The plan's subscriber limit is reached.                         |
| "This campaign cannot be sent yet."                          | The campaign is not ready; the reasons are in `problems`.       |
| A refused sender address                                     | The sender is not on an allowed domain. The message says which. |

```json theme={null}
{
    "message": "This campaign cannot be sent yet.",
    "problems": [
        "Add a visible unsubscribe link to the content, with {{ unsubscribe_url }}.",
        "Set the postal address of your organisation in the general settings."
    ]
}
```

## Retry or not

* **Retry** on `429`, on `5xx` and on network errors, with a growing delay and the same `Idempotency-Key`.
* **Do not retry** a `4xx`: the same call gives the same answer. Fix it first.