Docs

Errors

The error envelope and every error code the API returns.

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

Error envelope

{
  "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.