Errors

All errors return JSON with a detail field describing the problem:

{
  "detail": "Rate limit exceeded"
}

Validation errors (422) include the offending field path:

{
  "detail": [
    {
      "loc": ["body", "from"],
      "msg": "from address must use a verified domain",
      "type": "value_error"
    }
  ]
}

Status codes

Code	Meaning	Action
200	Success	—
201	Resource created	—
204	Success, no body	—
400	Bad request	Fix the request body or parameters.
401	Unauthorized	Check your Authorization header — missing, malformed, or revoked key.
403	Forbidden	Your key is valid but lacks permission for this endpoint (e.g. sending_access calling /pools/*).
404	Not found	Resource doesn’t exist or you can’t see it.
409	Conflict	Duplicate resource (e.g. domain already added, contact already in list).
413	Payload too large	Request body exceeded the limit (CSV uploads cap at 100MB).
422	Unprocessable	Validation failed — see detail for the field.
429	Too many requests	Back off; respect X-RateLimit-Reset.
500	Internal error	Retry with exponential backoff; if persistent, check status page.
503	Service unavailable	Redis or Postgres is degraded. Retry.

Common error scenarios

from domain not verified. Returns 400 with detail: "Domain not verified: example.com". Verify your domain before sending.

Recipient on suppression list. Returns 200 with the email status set to suppressed. Not an error — the request succeeded; the send was prevented.

Idempotency-key replay. Returns the original 200 response, not 409. The dedupe is silent.

Webhook delivery failure. 3AVA Mail retries failed webhook deliveries 5× with exponential backoff (1s, 4s, 16s, 1m, 5m). After that the delivery is marked failed and visible in the dashboard.