Errors

Errors carry an HTTP status and a body with a stable code and a human message. Match on code, never on the message.

{
  "code": "downgrade_blocked",
  "message": "You have 340 email addresses, which is more than Operator allows. Delete 90 first."
}

Status	Meaning	Codes you may see
400	Malformed request or invalid field	invalid_json, invalid_field, invalid_id, invalid_account_id, invalid_address, invalid_domain, invalid_cursor, invalid_box, invalid_key, invalid_url, invalid_status, invalid_platform, invalid_token, invalid_subject, reserved_domain, too_many_attachments, attachment_blocked, contact_sales, nothing_to_pay, provider_unavailable (card payment is not offered for that plan)
401	Missing, expired or revoked token, or a failed sign-in	unauthenticated, session_expired, no_such_account, challenge_expired
402	The plan does not allow it	allocation_exhausted, worker_limit_reached, plan_capability_required, domain_limit_reached, payment_required
403	Not permitted for this token or plan	plan_required, session_required, payment_required, device_paused, device_disabled, address_paused, address_suspended, inbox_suspended, not_your_address, reply_only, sending_off, account_suspended, account_protected, confirmation_required, https_required
404	No such record, or not yours	not_found, session_not_found, not_cancellable
409	Conflicts with the current state	downgrade_blocked, no_change, subscription_renewing, already_assigned, inbox_paused, address_taken, account_exists, already_used, lookup_required, duplicate, limit_reached, card_retrying, domain_in_use, domain_unavailable, domain_not_sending, already_added, store_billed, nothing_to_switch, id_taken, webhook_disabled, public_key_set, balance_held, window_closed, already_refunded, group_exists, group_limit_reached, already_member, team_limit_reached, epoch_conflict, and the support codes
413	Too large	too_large, attachments_too_large, message_too_large
426	Not a WebSocket upgrade	upgrade_required
429	Rate limited	rate_limited, daily_send_limit, with a Retry-After header
5xx	A failure on our side or at a provider	internal, send_failed, provider_error, provider_unavailable, storage_unavailable, sending_paused, support_unavailable, feature_disabled, code_unavailable, maintenance, read_only. Retry with backoff.

Codes worth handling

Code	What to do
session_required	The call needs a signed-in session. API keys cannot make it.
confirmation_required	Deleting the account needs a fresh proof of the recovery phrase. See Accounts.
plan_required	The plan does not include this. The message names the plan that does.
payment_required (403)	The account is paused after a missed payment. See Missed payments.
payment_required (402)	A plan change needs a payment. Use checkout.
rate_limited	Wait for Retry-After seconds.
daily_send_limit	The account has sent its plan’s mail for today. Sending resumes at 00:00 UTC.
sending_paused (503)	Sending is paused for today. It resumes at 00:00 UTC; receiving carries on.
maintenance, read_only (503)	Mailcycle is in maintenance. read_only still answers reads. Wait for Retry-After and try again.
lookup_required	Look the pairing code up again from the same account, then claim.
reply_only	The agent can only reply to whoever wrote the message it names.
sending_off	Sending is turned off for this agent.
store_billed	The App Store or Google Play bills the plan, so the web can’t take money for one until that subscription is cancelled there.
account_suspended	The account is suspended. Only the support endpoints still answer.
balance_held	The account balance still holds money you paid in. Ask for it back before deleting the account, or confirm it will be lost. See Accounts.