Error Codes

All errors return a JSON body with a detail field explaining what went wrong.

{
  "detail": "Human-readable error message"
}

HTTP Status Codes

Code	Meaning	When
200	OK	Successful read or update
201	Created	Resource created successfully
204	No Content	Resource deleted successfully
400	Bad Request	Invalid input or duplicate resource
403	Forbidden	Auth failure or quota exceeded
404	Not Found	Resource doesn’t exist or not owned by you
500	Internal Server Error	Unexpected server-side error

Common Errors

Authentication

Detail	Cause	Fix
Invalid authorization header format	Missing Bearer prefix	Use Authorization: Bearer YOUR_KEY
Invalid API key	Token not found in database	Check your API key
API key is deactivated	Token was revoked	Generate a new key
API key has expired	Token past expiration date	Create a new key or update expiration

Quotas

Detail	Cause	Fix
Domain quota exceeded: 5/5	All domain slots used	Upgrade plan or delete a domain
Mailbox quota exceeded for this domain: 3/3	Domain mailbox limit reached	Upgrade plan or delete a mailbox

Resources

Detail	Cause	Fix
El dominio ya existe en el servidor SaaS	Domain name taken	Choose a different domain
Este email (buzón) ya existe en el servidor SaaS	Email address taken	Choose a different email
El dominio asociado no existe	Domain not found for mailbox creation	Create the domain first
Dominio no encontrado	Domain doesn’t exist or not yours	Check the domain name
Usuario (buzón) no encontrado	Mailbox doesn’t exist or not yours	Check the email address

Error Handling Best Practices

1. Always check the status code before parsing the response body
2. Retry on 500 errors with exponential backoff (max 3 retries)
3. Don’t retry 400/403/404 — these are client errors that won’t resolve on retry
4. Log the detail field for debugging — it contains specific information about what went wrong