> ## 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.