Errors
Irisend API errors return a JSON body shaped { statusCode, name, message } so you can branch on the error name. See every error name and when it occurs.
| name | status | meaning |
|---|---|---|
| missing_required_field | 422 | A required field is missing from the request body. |
| invalid_idempotency_key | 400 | The `Idempotency-Key` header is not 1–256 characters. |
| invalid_idempotent_request | 409 | The `Idempotency-Key` was reused with a different request body. Use a new key, or retry with the exact same body. |
| concurrent_idempotent_requests | 409 | Another request with the same `Idempotency-Key` is already in flight. Retry once it completes. |
| invalid_from_address | 422 | The `from` (or another address) field doesn't parse as `[email protected]` or `Name <[email protected]>`. |
| validation_error | 403 / 422 | The body failed schema validation, or the JSON itself was malformed (422), or a business rule was violated — e.g. sending from an unverified domain, re-registering a domain name, or reusing a template alias/topic name (403). |
| invalid_access | 401 / 403 | An embed or hosted-preferences token is invalid or expired (401), or a sub-account-scoped key tried to act outside its own account (403). |
| invalid_parameter | 422 | A path parameter (e.g. `:id`) isn't a valid UUID. |
| missing_api_key | 401 | No `Authorization` header was sent. |
| restricted_api_key | 401 / 403 | A `sending_access` key called a management endpoint (401), or a domain-scoped key tried to send from a non-matching domain (403). |
| invalid_api_key | 403 | The API key is malformed or does not exist. |
| account_suspended | 403 | The team, or its parent account, has been suspended. |
| domain_reputation_paused | 403 | The sending domain's bounce/complaint rate tripped the reputation circuit breaker. Call `POST /domains/:id/unpause` once it's resolved. |
| daily_quota_exceeded | 429 | The team (or sub-account) hit its daily sending quota. |
| monthly_quota_exceeded | 429 | The team (or sub-account) hit its monthly sending quota. |
| rate_limit_exceeded | 429 | Your team exceeded its requests-per-second limit. |
| not_found | 404 | The endpoint, or a resource ID owned by a different team, does not exist. |
| internal_server_error | 500 | Something went wrong on our end. Safe to retry. |
| invalid_region | — | Reserved for Resend-catalogue parity; not currently returned by any endpoint. |
| method_not_allowed | — | Reserved for Resend-catalogue parity; not currently returned by any endpoint. |