# Errors

An error answers with a 4xx or 5xx status and a JSON body. `name` is stable, so branch on it in your code. `message` is for people and can change.

## Error Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | The error name from the list below. |
| `status` | integer | No | The HTTP status. |
| `message` | string | No | What went wrong. |
| `errors` | object[] | No | For a validation error, one entry for each problem. Empty for other errors. |
| `errors[].message` | string | No | What is wrong with the field. |
| `errors[].location` | string | No | The field that failed, such as `subject` or `tags.0.name`. `body` when the body is not valid JSON. |
| `request_id` | string \| null | No | The request id, also in the `X-Request-Id` header. |

## Error Names

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `validation_error` | 400 | No | A field is missing or invalid, or the body is not valid JSON. |
| `invalid_idempotency_key` | 400 | No | The Idempotency-Key header is not 1 to 256 printable ASCII characters. |
| `unauthorized` | 401 | No | The API key is missing, revoked or expired. |
| `forbidden` | 403 | No | The key cannot do this: a Sending key on a Full route, a key limited to one domain on a workspace route, a request from an address outside the IP allowlist, or a from domain the key is not limited to. A send also answers 403 when the domain is not verified, every recipient is suppressed, or sending is paused. |
| `limit_exceeded` | 403 | No | The workspace reached a limit, such as 100 topics. |
| `not_found` | 404 | No | The object does not exist in this workspace. |
| `conflict` | 409 | No | The object is in a state that does not allow the change, such as deleting a campaign that is sending, or the name is already taken. |
| `concurrent_idempotent_requests` | 409 | No | A request with the same Idempotency-Key is still running. |
| `payload_too_large` | 413 | No | The body is larger than 45 MB for Send Email, 10 MB for Send Batch or 2 MB for other routes. |
| `unsupported_media_type` | 415 | No | The body is not sent as `application/json`. |
| `invalid_idempotent_request` | 422 | No | The Idempotency-Key was used with a different request. |
| `rate_limit_exceeded` | 429 | No | Too many requests for this key, or the workspace reached its daily sending limit. See Rate Limits. |
| `unknown_error` | 500 | No | Something failed on our side. Retry later. |
| `service_unavailable` | 503 | No | A service we depend on did not answer. Wait for the seconds in `Retry-After` and try again. |

## Responses

| Status | Description |
| --- | --- |
| 400 | subject is required without a template. |
| 404 | Email not found. |

400:

```json
{
  "name": "validation_error",
  "status": 400,
  "message": "subject is required without a template",
  "errors": [
    {
      "message": "subject is required without a template",
      "location": "subject"
    }
  ],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```

404:

```json
{
  "name": "not_found",
  "status": 404,
  "message": "Email not found",
  "errors": [],
  "request_id": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e90"
}
```