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

# Errors

> Error formats for every Mailercloud API product, the Email API internal status-code table, and which errors are retryable.

Each product returns a distinct error envelope. This page maps all of them.

## Marketing API (`cloudapi.mailercloud.com`)

Standard HTTP status codes with a field-level error array:

```json theme={null}
{
  "errors": [
    { "field": "sender_email", "message": "sender_email must be a valid email address" }
  ]
}
```

| HTTP  | Meaning                                        | Retry?               |
| ----- | ---------------------------------------------- | -------------------- |
| `400` | Validation failed — see `errors[].field`       | No — fix the request |
| `401` | Missing/invalid API key                        | No                   |
| `404` | Resource not found                             | No                   |
| `429` | Rate limited — see [Rate limits](/rate-limits) | Yes, with backoff    |
| `5xx` | Server error                                   | Yes, with backoff    |

## Email API (`email-api.mailercloud.com`)

The Email API returns an envelope with its own internal status code system:

```json theme={null}
{ "status": "SUCCESS", "statusCode": 1000, "message": "NA" }
```

<Warning>
  **Always check `statusCode`, not just the HTTP status.** Some delivery-outcome codes are returned with HTTP `200` even though they represent a failure (e.g. `9007` Hard bounce). An agent or client that keys only off HTTP status will misread these as success.
</Warning>

### Internal status codes

| Code   | Meaning                                                            | Typical HTTP | Retry?                   |
| ------ | ------------------------------------------------------------------ | ------------ | ------------------------ |
| `1000` | Success                                                            | 200          | —                        |
| `9001` | Throttling error                                                   | 429          | ✅ backoff                |
| `9002` | Message sending quota exceeded                                     | 200          | ❌ raise quota            |
| `9003` | Authentication failure                                             | 403          | ❌                        |
| `9004` | Recipient address not specified                                    | 400          | ❌                        |
| `9005` | From field missing                                                 | 400          | ❌                        |
| `9006` | Soft bounce (temporarily deferred)                                 | 200          | ✅ later                  |
| `9007` | Hard bounce                                                        | 200          | ❌ remove address         |
| `9008` | Email reported as spam                                             | 200          | ❌                        |
| `9009` | Email unsubscribed                                                 | 200          | ❌                        |
| `9010` | Email in suppression list                                          | 200          | ❌                        |
| `9011` | Sender address not verified                                        | 400          | ❌ verify sender          |
| `9012` | ESP rejected message                                               | 200          | ❌                        |
| `9013` | Request to ESP expired                                             | 200          | ✅                        |
| `9014` | ESP unavailable                                                    | 500          | ✅ backoff                |
| `9015` | IP not whitelisted with ESP                                        | 401          | ❌                        |
| `9016` | Subject field empty                                                | 400          | ❌                        |
| `9017` | Invalid sender address                                             | 400          | ❌                        |
| `9018` | Invalid email address                                              | 400          | ❌                        |
| `9019` | Recipient's mailbox is full                                        | 200          | ✅ later                  |
| `9021` | Mailbox not found on email server                                  | 200          | ❌                        |
| `9022` | Unsupported version                                                | 400          | ❌ — use `1.0`/`2.0`      |
| `9024` | Authorization failure                                              | 403          | ❌                        |
| `9452` | Message overloading                                                | 200          | ✅ backoff                |
| `9512` | Host email server not found                                        | 200          | ❌                        |
| `9999` | Unknown error occurred                                             | 200          | ✅ once, then investigate |
| `8000` | Campaign ID required for inbox tracking                            | 400          | ❌                        |
| `8001` | Campaign ID format invalid (alphanumeric/hyphen/tilde, ≤100 chars) | 400          | ❌                        |

## Email Verifier API (`verify.mailercloud.com`)

Simple error object with standard HTTP semantics:

```json theme={null}
{ "error": "Invalid or inactive API key" }
```

| HTTP  | Meaning                                              | Retry?            |
| ----- | ---------------------------------------------------- | ----------------- |
| `400` | Invalid request (bad JSON, >50 emails, missing file) | No                |
| `401` | Missing/invalid API key                              | No                |
| `402` | Insufficient credits                                 | No — buy credits  |
| `413` | File too large (>10 MB or >100k emails)              | No                |
| `503` | Service busy                                         | Yes, with backoff |