Errors

Every API error is a JSON problem object (RFC 9457) with a stable code, a message and a fix written for the agent that has to act on it. Branch on code and the HTTP status, never on message: messages contain values such as a field name or a limit.

{
  "type": "https://docs.replyz.io/errors/not_found",
  "code": "not_found",
  "status": 404,
  "message": "Inbox not found.",
  "fix": "List your inboxes with GET /v1/inboxes.",
  "docs": "https://docs.replyz.io/errors/not_found.md"
}

• Content-Type: application/problem+json; status equals the HTTP status.
• The members are exactly type, code, status, message, fix and docs. There is no title, detail or instance; message takes the place of detail.
• One problem per response: the first failing check wins. There is no list of field errors.
• Every problem response carries Cache-Control: no-store. A 401 carries WWW-Authenticate: Bearer realm="replyz"; a 405 carries Allow.
• Retry-After (whole seconds) comes with rate_limited, signup_limit, inbox_create_limit, too_many_waits, extract_limit, signups_disabled and, in one case, address_unavailable. There are no X-RateLimit-* headers.
• Order of checks: the route (404, 405, before the key), then the API key (401), then the operation’s own checks.
• Unknown query parameters and unknown JSON fields are ignored.

All codes

Code	HTTP	Meaning
address_unavailable	503	No free address could be found (practically never happens).
extract_limit	429	A flagged account used its 10 extractions for this UTC hour.
idempotency_in_progress	409	A request with the same Idempotency-Key is still running, or stopped before it answered.
inbox_create_limit	429	The account reached its daily inbox-creation cap.
inbox_limit	409	The account already has as many live inboxes as it may have.
internal_error	500	Something failed on Replyz’s side.
invalid_json	400	The request body is not a JSON object.
invalid_request	400	A field, header or query parameter is missing or invalid.
method_not_allowed	405	The path exists, but not with this HTTP method.
name_reserved	400	The name would make a reserved address.
not_found	404	The route or the resource does not exist for this account.
org_not_active	403	The account is expired or suspended, so it cannot create or change inboxes.
payload_too_large	413	The request body is larger than 16,384 bytes.
pow_expired	400	The signup challenge is too old or out of date.
pow_invalid	400	The proof of work was rejected.
pow_reused	400	The signup challenge was already used.
rate_limited	429	Too many signup requests from this network in the last minute.
signup_limit	429	This network already made 20 signups today (UTC).
signups_disabled	503	Replyz has paused new signups.
too_many_waits	429	The account already holds 5 long-polls.
unauthorized	401	The API key is missing, malformed, unknown or revoked.

Mail that is refused (SMTP)

Inbound mail is not an API call, so it has no problem object. The sending server gets one of these answers:

Answer	When
555 5.7.1 mailbox unavailable. (permanent)	One text for every rejection: unknown or malformed address, deleted inbox, account expired or suspended, receiving paused, message over 10 MiB, or the monthly receive cap reached. The sender cannot tell which. Replyz gives only the text mailbox unavailable; Cloudflare puts its own code in front.
421 4.3.0 (temporary; the sender retries)	Handling the message failed on Replyz’s side, for example storing it.

The agent is not told about refused mail. See Receiving mail.

Not a problem: 499

wait, GET /v1/messages/{id} and POST /v1/messages/{id}/extract are designed to end with 499 and an empty body when the client disconnected before the answer was sent; nothing is then marked as read (an extraction result may already be stored). A connected client never receives it. This depends on a platform signal that cannot be tested locally, so it is not verified yet.