Menu Errors

Reference

Errors

Every failure is JSON – { "error": "<code>", "message": "<phrase>" }. Switch on error, not on the status alone; message is a fixed English phrase for whoever reads the log.

Error codes

StatusCodeWhen
400bad_requestA parameter of the wrong type or out of range (size=500, timeout=0), unreadable JSON, localPart without domain or a malformed local part.
401unauthorizedNo Authorization header, or a key that is unknown, revoked or expired. Any endpoint.
402quota_exhaustedMonthly mailbox quota spent. POST /v1/mailboxes only – reads never spend it.
403plan_forbiddenYour plan has no API access, or it does not allow a custom localPart.
404not_foundNo such active mailbox, message or attachment of yours – an expired mailbox included; or a domain your plan cannot use.
409address_takenThe requested address exists already – forever, deleted ones included.
429rate_limit_exceededRequests per minute spent. Any endpoint; Retry-After says when to come back.
429too_many_waitsToo many waits of yours held open at once. GET …/messages/wait only, with Retry-After: 1.

Besides these, any call can meet 405 method_not_allowed, 413 payload_too_large or 415 unsupported_media_type (a body that is not JSON), 500 internal_server_error, and 503 internal_server_error with Retry-After when the service is momentarily overloaded.

402 – the monthly quota is spent

Only POST /v1/mailboxes can return it. Next to the envelope the body carries your quota – limit, used and resetsAt, the first day of the next month at 00:00 UTC – and upgradeUrl, the plans page. There is no Retry-After – waiting a minute does not bring the quota back. A create that fails for any reason spends no quota.

Response
HTTP/1.1 402 Payment Required
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 38
X-RateLimit-Reset: 1792659660

{
  "error": "quota_exhausted",
  "message": "monthly mailbox quota exhausted",
  "limit": 20,
  "used": 20,
  "resetsAt": "2026-11-01T00:00:00.000Z",
  "upgradeUrl": "https://fake-email.pro/pricing"
}

429 – too many requests this minute

Requests are metered per minute and per user, not per key: every /v1 call counts, reads included. Sleep for Retry-After seconds and retry; your number is requestsPerMinute in GET /v1/limits, and Limits has the rest.

Response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 17
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1792659660

{"error":"rate_limit_exceeded","message":"rate limit exceeded"}
Something missing, confusing or wrong on this page? Tell us