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

# Errors

> HTTP error codes returned by the Paubox Email API, with common causes and fixes.

The Paubox Email API uses standard HTTP status codes. All error responses include a JSON body with a `message` field describing the problem.

## Status codes

| Code  | Meaning               | Common cause                                                                    |
| :---- | :-------------------- | :------------------------------------------------------------------------------ |
| `200` | OK                    | Request succeeded                                                               |
| `400` | Bad Request           | Invalid request body: see checklist below                                       |
| `401` | Unauthorized          | Missing or invalid API key                                                      |
| `403` | Forbidden             | API key valid but lacks permission for this action                              |
| `404` | Not Found             | Resource (e.g. tracking ID) does not exist                                      |
| `422` | Unprocessable Entity  | Request is well-formed but semantically invalid (e.g. unverified `from` domain) |
| `429` | Too Many Requests     | Rate limit exceeded; see [Limits](/email-api/limits)                            |
| `500` | Internal Server Error | Unexpected server-side error                                                    |
| `502` | Bad Gateway           | Upstream connectivity issue; retry with backoff                                 |
| `503` | Service Unavailable   | Temporary outage; check [status.paubox.com](https://status.paubox.com)          |
| `504` | Gateway Timeout       | Request timed out; retry with backoff                                           |

## 400 Bad Request: debugging checklist

A `400` usually means the request body is missing a required field or contains an invalid value. Work through this list:

<Warning>
  **The most common causes of 400 Bad Request:**

  * **`from` domain not verified**: the sender address must belong to a domain you have verified in [Email API > Settings](https://next.paubox.com/emailapi/settings). Sending from `@gmail.com` or any unverified domain always returns a 400.
  * **Missing `subject`**: `data.message.headers.subject` is required.
  * **Empty `recipients` array**: `data.message.recipients` must contain at least one valid email address.
  * **Invalid base64 in attachment**: the `content` field of every attachment must be valid base64-encoded data.
  * **No message body**: at least one of `text/plain` or `text/html` must be present in `data.message.content`.
</Warning>

## 401 Unauthorized

The API key is missing, malformed, or does not match the username in the URL.

```bash theme={null}
# Check: does the base URL username match the account that owns the key?
https://api.paubox.net/v1/YOUR_USERNAME/messages
#                          ^^^^^^^^^^^^
# This must be YOUR endpoint username, not your email address.
```

## 429 Too Many Requests

You have exceeded the rate limit for your plan. Back off and retry. See [Limits](/email-api/limits) for rate limit details.

For high-volume sending, use the [bulk messages](/email-api/bulk-messages) endpoint (recommended max 50 per request) rather than looping over individual `/messages` calls.

## Example error response

```json theme={null}
{
  "errors": "Sender domain not verified"
}
```