# Errors (/errors)

Alienmail uses standard HTTP status codes. A `2xx` means success. Anything else has a JSON body with an `error` object:

```json
{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid. Check the fields.",
    "fields": { "dailyLimit": "Too big: expected number to be <=2000" }
  }
}
```

- `code` is stable: use it in your code.
- `message` is written for people and may change.
- `fields` comes with validation errors, including bad query parameters like `status` or `cursor`. It maps each field to what is wrong with it. Nested fields use dots (`leads.0.firstName`, `custom.plan`), and `_` stands for the body as a whole.

Unknown paths under `/api/v1` and unsupported methods answer in this format too.

## Request bodies [#request-bodies]

Send bodies as JSON with the header `Content-Type: application/json`. A body with another content type is refused with `415`, and one that isn't valid JSON with `400` and the code `invalid_json`.

Bodies are checked strictly. A field the endpoint doesn't know is refused with `400` instead of being ignored, so a typo like `first_name` for `firstName` can't pass silently:

```json
{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid. Check the fields.",
    "fields": { "leads.0": "Unrecognized key: \"first_name\"" }
  }
}
```

## Status codes [#status-codes]

| Status | Code | Meaning |
|---|---|---|
| `200` | | Success. |
| `400` | `bad_request` | The request is invalid. Check `fields`. |
| `400` | `invalid_json` | The body isn't valid JSON. |
| `401` | `unauthorized` | Missing or invalid API key. See [Authentication](/authentication). |
| `403` | `forbidden` | The key's role lacks the permission the endpoint needs. |
| `404` | `not_found` | The campaign, lead or mailbox doesn't exist in your workspace, or the path isn't an endpoint. An id that isn't a number, or an email that isn't an email address, is a `404` too. |
| `405` | `method_not_allowed` | The endpoint doesn't support this method. The `Allow` header lists the ones it does. |
| `409` | `conflict` | The campaign, lead or mailbox is in a state that doesn't allow the request. `message` says why. |
| `415` | `unsupported_media_type` | The body isn't sent as `application/json`. |
| `429` | `rate_limited` | Too many requests. Wait for `Retry-After` seconds. |
| `500` | `server_error` | Something went wrong on our side. Retry later. |

## Conflicts [#conflicts]

A `409` means the request was understood but can't be done right now. Common cases:

| Request | Refused when |
|---|---|
| [Start a campaign](/api-reference/campaigns/startCampaign) | It is archived, its end date has passed, no email step has content, or no mailbox on it is active and connected. |
| [Pause a campaign](/api-reference/campaigns/pauseCampaign) | It isn't active. |
| [Add](/api-reference/leads/addLeads) or [remove](/api-reference/leads/removeLeads) leads | The campaign is archived. |
| [Update a lead](/api-reference/leads/updateLead) | The campaign is completed or archived, or it is active and the lead has already been emailed. |

## Retrying [#retrying]

- `429` and `5xx` are safe to retry after a pause. Back off exponentially for `5xx`.
- Don't retry other `4xx` responses unchanged: they will fail the same way.
- Every write in this API is safe to repeat. Adding a lead who is already in the campaign doesn't add them twice, removing one who is gone counts them in `notInCampaign`, and starting an active campaign or pausing a paused one returns it unchanged. There are no idempotency keys.