Error Reference

All errors return a JSON object with an error field:

{
  "error": "Human-readable error message",
  "upgrade": "POST /v1/billing/upgrade to get a checkout URL"
}

The optional upgrade field appears when the error is due to a plan limitation that can be resolved by upgrading.

• 200 — Success
• 201 — Resource created
• 400 — Bad request (invalid input, missing required fields)
• 401 — Unauthorized (missing or invalid API key)
• 403 — Forbidden (plan limit, scoped key, email not verified)
• 404 — Resource not found
• 409 — Conflict (duplicate resource)
• 413 — Payload too large (file or message size limit)
• 429 — Rate limited (daily send limit or API rate limit)
• 500 — Internal server error
• 503 — Service unavailable (dependency down)

Rate limiting (429)

{
  "error": "Daily send limit exceeded. Limit resets at midnight UTC.",
  "upgrade": "POST /v1/billing/upgrade to get a checkout URL"
}

Check the X-RateLimit-Remaining header to monitor your remaining quota before hitting the limit.

Plan limits (403)

{
  "error": "Free plan limited to 1 mailbox. Upgrade to create more.",
  "upgrade": "POST /v1/billing/upgrade to get a checkout URL"
}

Suppressed address (400)

{
  "error": "Recipient address is on the suppression list: [email protected]"
}

Remove the address from the suppression list if you believe it's now valid.