# Errors

> The error envelope and every error code the API returns.

Source: https://aimulti.inbox/docs/errors/

Errors use standard HTTP status codes and one JSON envelope. Branch on `code`, which is stable; `message` is for humans and may change.

```json
{
  "name": "Forbidden",
  "code": "limit_exceeded",
  "message": "the free plan allows 3 inboxes"
}
```

## Codes

| Code | Status | Meaning |
| --- | --- | --- |
| `missing_authorization` | 401 | No API key in the request. |
| `unknown_api_key` | 401 | The API key is not valid. |
| `validation_error` | 400 | A field is missing or malformed. The message names it. |
| `not_found` | 404 | The resource does not exist in your organization. |
| `already_exists` | 409 | The inbox address or domain is taken. |
| `domain_not_verified` | 403 | The domain is not verified, or does not belong to your organization. |
| `conflict` | 409 | Idempotency-Key reused with a different request, or the first request is still running. |
| `cannot_delete` | 409 | The domain still has inboxes. |
| `limit_exceeded` | 403 or 429 | A plan limit: inboxes or domains (403), daily or monthly sends (429). |
| `rate_limit_exceeded` | 429 | Too many requests. Wait for the `Retry-After` header. |
| `rate_limited` | 429 | The plan's 5 minute send burst limit is reached. Retry after the `Retry-After` seconds. |
| `address_quarantined` | 409 | The address belonged to an inbox deleted less than 90 days ago; it is reserved until the date in the message. |
| `sending_paused` | 403 | Sending from the inbox or organization is paused because too many recent sends hard bounced. Contact support. |
| `missing_permission` | 403 | The API key is scoped and lacks the permission this endpoint needs. |
| `permission_escalation` | 403 | A key tried to grant or revoke permissions it does not hold. |
| `api_key_expired` | 401 | The API key passed its expiry date. |
| `not_held` | 409 | Release of a message that is not held for review (still pending screening, clean or already released). |
| `billing_disabled` |  |  |
| `billing_provider_error` |  |  |
| `already_subscribed` |  |  |
| `no_billing_account` |  |  |
| `invalid_signature` |  |  |
| `too_many_streams` | 429 | The API key already has 5 open event streams. Close one first. |
| `payload_too_large` | 413 | Attachments or request body too large. |
| `attachment_infected` |  |  |
| `antivirus_unavailable` |  |  |
| `auth_disabled` |  |  |
| `provider_not_configured` |  |  |
| `invalid_magic_link` |  |  |
| `invalid_state` |  |  |
| `code_rejected` |  |  |
| `email_not_verified` |  |  |
| `provider_unavailable` |  |  |
| `email_delivery_failed` |  |  |
| `invalid_refresh_token` |  |  |
| `token_expired` |  |  |
| `unknown_token` |  |  |
| `session_revoked` |  |  |
| `access_denied` |  |  |
| `internal_error` | 500 | Unexpected error on our side. Safe to retry with the same Idempotency-Key. |

## Retrying

* Retry `429` and `5xx` with backoff. Honor `Retry-After` when present.
* Do not retry `4xx` other than `429` without changing the request.
* Always send an `Idempotency-Key` on send and reply, so retries cannot duplicate mail.