# Errors

> Every error returns a JSON body with statusCode, name, and message.

MailBlastr uses conventional HTTP status codes: `2xx` for success, `4xx` for problems with the request (a missing field, an invalid key, an unverified domain), and `5xx` for server errors. Every error response has the same shape:

```json
{
  "statusCode": 403,
  "name": "invalid_api_key",
  "message": "API key is invalid or has been revoked."
}
```

## Error names

| name | Status | Meaning |
| --- | --- | --- |
| `invalid_idempotency_key` | 400 | The `Idempotency-Key` is malformed. It must be between 1 and 256 characters. |
| `validation_error` | 400 | One or more fields in the request failed validation. The message details which field and error. |
| `missing_api_key` | 401 | No API key in the authorization header. Include `Authorization: Bearer YOUR_API_KEY`. |
| `restricted_api_key` | 401 | This API key is restricted to only send emails. Use a key with full access for other actions. |
| `invalid_api_key` | 403 | The API key is invalid, expired, or revoked. Generate a new key in the dashboard. |
| `validation_error` | 403 | A domain-related rejection — e.g. the `from` domain is not verified, the domain does not match a verified domain, or a domain is already registered. |
| `not_found` | 404 | The requested endpoint or resource does not exist (or is not yours). |
| `invalid_idempotent_request` | 409 | The same idempotency key was used with a different request payload. Change the key or the payload. |
| `concurrent_idempotent_requests` | 409 | The same idempotency key was used while the original request is still in progress. Try again later. |
| `invalid_attachment` | 422 | An attachment must have either `content` or `path`. |
| `invalid_from_address` | 422 | The `from` field is invalid. Use `email@example.com` or `Name <email@example.com>`. |
| `invalid_to_address` | 422 | A recipient address is not a valid email address. |
| `invalid_access` | 422 | Access must be `full_access` or `sending_access`. Make sure the key has the necessary permissions. |
| `missing_required_field` | 422 | The request body is missing one or more required fields (e.g. `from`, `to`, `subject`). |
| `daily_quota_exceeded` | 429 | You have reached your daily email quota. Wait 24 hours or upgrade your plan. Sent and received emails both count. |
| `monthly_quota_exceeded` | 429 | You have reached your monthly email quota. Upgrade your plan to increase it. Sent and received emails both count. |
| `rate_limit_exceeded` | 429 | Too many requests. Read the rate-limit response headers and reduce your request rate. |
| `application_error` | 500 | An unexpected error occurred. Safe to retry idempotent requests later. |
| `internal_server_error` | 500 | An unexpected error occurred. Try the request again later. |

> **Note:** The same `validation_error` name is returned with either a `400` (a field failed validation) or a `403` (a domain-related rejection) status, so inspect both `statusCode` and `message`.