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

# Errors

> Error format and error code reference

# Errors

All Numonic API errors follow a consistent format with machine-readable codes and developer-friendly context.

## Error format

```json theme={null}
{
  "success":   false,
  "error": {
    "code":    "DOMAIN_NOT_VERIFIED",
    "message": "The from address domain is not verified",
    "why":     "The domain example.com has not completed DNS verification",
    "action":  "Add the required DNS records and wait for verification to complete"
  },
  "timestamp": "2026-04-09T10:30:00.000Z",
  "path":      "/api/v1/send"
}
```

The `why` and `action` fields are included on most errors to give you a clear explanation of what went wrong and what to do about it.

## Error codes

| Code                   | HTTP Status | Description                                                                                            |
| ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------ |
| `BAD_REQUEST`          | 400         | Malformed request                                                                                      |
| `DOMAIN_NOT_VERIFIED`  | 400         | Sending from a domain that hasn't completed verification                                               |
| `UNAUTHORIZED`         | 401         | Missing or invalid credentials                                                                         |
| `FORBIDDEN`            | 403         | Insufficient permissions                                                                               |
| `DOMAIN_NOT_OWNED`     | 403         | Domain belongs to another tenant                                                                       |
| `NOT_FOUND`            | 404         | Resource not found                                                                                     |
| `ROUTE_NOT_FOUND`      | 404         | Unknown endpoint                                                                                       |
| `CONFLICT`             | 409         | Resource conflict — e.g. domain already registered, or idempotency key reused with a different payload |
| `VALIDATION_ERROR`     | 422         | Request body validation failed — missing required fields or invalid format                             |
| `RATE_LIMIT_EXCEEDED`  | 429         | Too many requests — back off and retry                                                                 |
| `INTERNAL_ERROR`       | 500         | Server error                                                                                           |
| `UPSTREAM_ERROR`       | 502         | Upstream service (SES) returned an error                                                               |
| `UPSTREAM_UNREACHABLE` | 503         | Upstream service timed out                                                                             |

## Rate limits

| Window             | Limit        |
| ------------------ | ------------ |
| Per second (burst) | 3 requests   |
| Per 10 seconds     | 20 requests  |
| Per minute         | 100 requests |

When rate limited, you'll receive `429 RATE_LIMIT_EXCEEDED`. Use exponential backoff and retry.