# Email API errors

> Email API errors: every HTTP status and error name the Cresca API returns, what each one means, and which errors to retry with exponential backoff.

Canonical: https://www.cresca.xyz/docs/errors
Last updated: 2026-11-05

Email API errors: what each error response means, and which ones to retry.

Successful requests return `2xx`. Errors return a JSON body with the HTTP status, a stable machine-readable `name` and a human-readable `message`:

Response 422

```json
{
  "statusCode": 422,
  "name": "validation_error",
  "message": "Invalid `to` field. The email address needs to follow the `email@example.com` or `Name <email@example.com>` format."
}
```

Branch on `name`; messages may be reworded over time.

## Error names

| Status | name | Meaning | Retry? |
| --- | --- | --- | --- |
| 400 | `invalid_idempotency_key` | The Idempotency-Key is not 1 to 256 characters. | No |
| 401 | `missing_api_key` | No API key in the request. | No |
| 401 | `restricted_api_key` | A sending-access key called an endpoint that needs full access. | No |
| 403 | `invalid_api_key` | The key is unknown, revoked, or the account is suspended. | No |
| 403 | `invalid_from_address` | The from address is not an active sender on a verified domain, or the key is limited to another domain. | No |
| 403 | `plan_inactive` | Your plan does not allow adding contacts. | No |
| 404 | `not_found` | The email, template or endpoint does not exist in your account. | No |
| 409 | `invalid_idempotent_request` | The Idempotency-Key was already used with a different body. | No |
| 409 | `concurrent_idempotent_requests` | A request with the same key is still running. | Yes, shortly |
| 422 | `missing_required_field` | A required field is missing. | No |
| 422 | `validation_error` | A field is invalid, or a template variable is missing. | No |
| 413 | `validation_error` | The request body is larger than 10 MB. | No |
| 422 | `invalid_attachment` | An attachment is too large, not base64, or of a blocked type. | No |
| 429 | `rate_limit_exceeded` | More requests per second than your plan allows. | Yes, after retry-after |
| 429 | `monthly_quota_exceeded` | The plan’s monthly email allowance is used up, or the plan is not active. | No |
| 500 | `application_error` | Something went wrong on Cresca’s side. | Yes, with backoff |
| 503 | `service_unavailable` | Sending, or the check of your plan, is temporarily unavailable. | Yes, with backoff |

## Retry strategy for email API errors

Retry `429`, `5xx`, timeouts and network errors with exponential backoff and jitter, and send an [Idempotency-Key](https://www.cresca.xyz/docs/idempotency) so retries never duplicate an email. Do not retry other `4xx` errors: the same request will fail the same way.

[Previous Rate limits and quotas](https://www.cresca.xyz/docs/rate-limits) [Next Send email](https://www.cresca.xyz/docs/api-reference/send-email)

Last updated November 5, 2026. Questions? [lalit@cresca.xyz](mailto:lalit@cresca.xyz)
