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
| Status | Code | When |
|---|---|---|
| 400 | bad_request | A parameter of the wrong type or out of range (size=500, timeout=0), unreadable JSON, localPart without domain or a malformed local part. |
| 401 | unauthorized | No Authorization header, or a key that is unknown, revoked or expired. Any endpoint. |
| 402 | quota_exhausted | Monthly mailbox quota spent. POST /v1/mailboxes only – reads never spend it. |
| 403 | plan_forbidden | Your plan has no API access, or it does not allow a custom localPart. |
| 404 | not_found | No such active mailbox, message or attachment of yours – an expired mailbox included; or a domain your plan cannot use. |
| 409 | address_taken | The requested address exists already – forever, deleted ones included. |
| 429 | rate_limit_exceeded | Requests per minute spent. Any endpoint; Retry-After says when to come back. |
| 429 | too_many_waits | Too 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.
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.
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"}