Errors

Errors return JSON with an error code and, where noted, extra fields:

{ "error": "plan_max_mailboxes_reached", "limit": 1 }

Everywhere

Status	Meaning
`401`	Missing or invalid API key
`404`	The resource does not exist, or the key’s scope does not include it. The two are deliberately indistinguishable
`429`	Rate limit exceeded. Wait for `Retry-After` seconds

Status	`error`	Extra	Meaning
`400`	`invalid_name`		Name is empty or too long
`400`	`invalid_subdomain`		Subdomain has characters outside `a-z`, `0-9`, `-`
`400`	`invalid_retention`	`max`	Retention exceeds the plan ceiling in days
`400`	`invalid_group_id`, `group_not_found`		Bad group reference
`409`	`subdomain_taken`		Another mailbox has that subdomain
`409`	`subdomain_reserved`		Subdomain is reserved by mailcatchr
`409`	`plan_max_mailboxes_reached`	`limit`	Plan mailbox cap reached

await answers 204 with no body on timeout. It is not an error.

Status	`error`	Extra	Meaning
`400`	`invalid_body`		No `textBody` or `htmlBody`, or a malformed address
`403`	`outbound_disabled`		Outbound is off for the mailbox, or the plan does not include it
`422`	`invalid_from_domain`	`domain`	`from` is not on a verified sending identity
`422`	`suppressed_recipients`	`recipients`	One or more recipients are on the suppression list
`429`	`daily_outbound_limit_reached`	`count`, `limit`	Daily send cap reached
`402`	`insufficient_funds`	`balance_cents`, `required_cents`	Wallet cannot cover the send
`402`	`storage_limit_reached`	`limit_bytes`	Workspace storage is full

Status	`error`	Extra	Meaning
`400`	`invalid_<field>`		The named field failed validation, for example `invalid_forward_url`
`409`	`hook_limit_reached`	`limit`	Plan interceptor cap reached