What does an error look like?
422 Unprocessable Entity
{
"error": {
"code": "validation_error",
"message": "to: 'amina@' is not a valid email address",
"request_id": "req_8f2c1a9d03b44e7a1c5d"
}
}Every response, successful or not, carries an X-Request-Id header with the same identifier.
Which error codes can I get?
| HTTP | code | Meaning |
|---|---|---|
| 400 | bad_request | The request could not be processed as sent. |
| 401 | invalid_credentials | Missing or wrong API key, mailbox email or app password, or the app password was revoked. |
| 402 | payment_required | The domain is blocked because the subscription is overdue. |
| 403 | forbidden | App password not allowed from this IP, or the mailbox is disabled. |
| 404 | not_found | Message, folder or attachment not found. |
| 413 | payload_too_large | An uploaded attachment is over 25 MB. |
| 422 | validation_error | A field is missing or invalid. The message names the field. |
| 429 | rate_limited | Too many requests. See Retry-After. |
| 429 | daily_limit_exceeded | The key's daily sending limit was reached. |
| 502 | upstream_error | The mail server could not complete the request. Safe to retry with backoff. |
How should I handle errors?
- 4xx (except 429): fix the request. Retrying will not help.
- 429: wait for
Retry-After, then retry. - 5xx: retry with exponential backoff, using an idempotency key for sends.