Errors

Every error from the API is JSON, with an error code for your program and a message for a person. A request that fails validation also has issues, one per invalid field:

{
  "error": "invalid_request",
  "message": "The request is invalid: to.0: Invalid email address",
  "issues": [{ "path": "to.0", "message": "Invalid email address" }]
}

Some errors add fields, such as the suppressed recipients or when a limit resets. Each operation’s page in the reference lists them.

Two refusals are plain text, not JSON: 429 Too Many Requests and 413 Request Entity Too Large. They come from the proxy in front of the API, as Limits explains. A body over the size limit meets the proxy first, so it gets the plain-text 413.

Retry or fix

• rate_limited (429): wait the seconds in retryAfter, which the Retry-After header also gives, then send again. The refused message was not stored. If you meet this limit often, ask support to raise it.
• sending_disabled (503): sending is disabled for everyone for the moment. Retry after the seconds in the Retry-After header.
• monthly_cap_reached (429): wait until resetsAt, or have an administrator of your account raise the cap under Account › Usage. Limits says how far they can raise it.
• A 5xx status: retry with a growing delay, under the same idempotency key so the message cannot go twice.
• Any other code: read its meaning in the table below. Most need a fix to the request or the account, and fail the same way if sent again unchanged.

On rate_limited and monthly_cap_reached, scope says whose limit it is: the account’s (account), the server’s own (server) or the test servers’ (test). Test mail never counts toward the account’s monthly cap. A webhook can warn you before the cap is used up.

When an account cannot send

• payment_required (402): the account has no active payment, for instance before a card is saved. Activate payment under Account › Billing in the dashboard. Every send from a live server fails until then.
• account_not_active (403): Sendora has not approved the account yet. Every account is reviewed by hand before a live server can send. A test server works before that.
• account_paused (403): Sendora has paused the account, for instance after a failed payment. Support tells you why. A pause for an unpaid subscription lifts once you save a working card under Account › Billing.

Over SMTP, the same refusals arrive as SMTP replies, which SMTP submission lists.

Error codes