Error Handling

All errors return a JSON body with an error code and a human-readable message.

Error Format

{
  "error": "address_taken",
  "message": "This email address is already in use"
}

Field	Type	Description
error	string	Machine-readable error code
message	string	Human-readable description

HTTP Status Codes

Code	Meaning	When
200	OK	Successful read or update
201	Created	Resource created (account, webhook, etc.)
204	No Content	Successful delete
400	Bad Request	Missing or malformed request body
401	Unauthorized	Missing, invalid, or expired token
403	Forbidden	Quota or limit exceeded
404	Not Found	Resource does not exist
409	Conflict	Resource already exists (duplicate address)
410	Gone	Message or resource has expired
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Common Error Codes

Account Errors

Error Code	Status	Description
invalid_address	400	Email address format is invalid
invalid_domain	400	Domain is not available for registration
password_too_short	400	Password must be at least 6 characters
address_taken	409	Email address is already registered
account_limit_reached	403	Maximum mailbox limit reached
invalid_credentials	401	Wrong email or password
invalid_token	401	Token is missing, invalid, or expired

Message Errors

Error Code	Status	Description
not_found	404	Message does not exist
expired	410	Message has been auto-deleted
invalid_index	400	Attachment index out of range

Pro Errors

Error Code	Status	Description
domain_limit_reached	403	Maximum custom domain limit reached
domain_already_exists	409	Domain already registered
webhook_limit_reached	403	Maximum webhook limit reached
domain_expired	410	Domain verification expired

Handling Errors

const res = await fetch('https://api.mail.cx/api/messages', {
  headers: { 'Authorization': `Bearer ${token}` }
});

if (!res.ok) {
  const body = await res.json();
  console.error(`Error ${res.status}: [${body.error}] ${body.message}`);

  if (res.status === 401) {
    // Token expired — re-authenticate
  } else if (res.status === 429) {
    // Rate limited — wait and retry
  }
}