Errors come back as JSON with the HTTP status, a stable name you can check in code, and a message for people:
{
"statusCode": 422,
"name": "validation_error",
"message": "The `to` field is required."
}
Error names
| Status | name | What to do |
|---|---|---|
| 401 | missing_api_key | Send Authorization: Bearer <key>. |
| 402 | insufficient_credits | Your plan has no email validations left this month. See Validate email addresses. |
| 403 | invalid_api_key | The key is wrong or revoked, or the account is disabled. Check the key or create a new one. |
| 403 | restricted_api_key | The key cannot do this: a sending key on a full-access endpoint, a key limited to another domain, an account without API access or without an active subscription. |
| 403 | invalid_from_address | The from domain is not verified. Verify your domain. |
| 404 | not_found | No email or key with that ID belongs to your account. |
| 409 | invalid_idempotent_request | The Idempotency-Key was already used with a different request body. Use a new key. |
| 422 | validation_error | A field is missing or invalid. The message names the field. |
| 429 | Too many requests. Wait for the number of seconds in the Retry-After header. See Rate limits. |
Retrying
- Retry
429and5xxresponses with exponential backoff. - Do not retry
4xxerrors other than429without changing the request. - Always retry with the same
Idempotency-Key, so a request that actually succeeded is not sent twice. See Idempotency.