The shape
The message says what happened and what to change. It never quotes an address, a subject, a body or a key you sent. Every answer, error or not, carries an x-request-id header: quote it when you write to hello@mydomainshub.com. A 429 carries retry-after, in seconds.
Every name
| name | Status | When | What to do |
|---|---|---|---|
validation_error | 422 | The request is not valid: the message names each field and what is wrong with it, or the content rule that refused the email (see Limits). Also 409 (an Idempotency-Key reused for a different request, or an email that has already left the queue), 413 (a request over 4 MB) and 405 (a method the path does not take). | Fix the request. Sending it again unchanged gets the same answer. |
unauthorized | 401 | The API key is missing, malformed, wrong or revoked. | Send Authorization: Bearer with a live key from the dashboard. |
forbidden | 403 | The key may not do this: a sending key reading or changing emails, a key limited to another domain, or the sandbox refusing a recipient who is not a member. Also while a new account is still being set up for sending. | Use a key with the access it needs, or the right from address. In the sandbox, send to your own members. For a new account, try again in a few minutes. |
not_found | 404 | Nothing with that id belongs to this account — or the path does not exist. | Check the id and that the key is this account’s. |
rate_limited | 429 | More requests with this key than it may make: 10 a second, with bursts of 20. | Wait for the seconds in retry-after, then send again. |
quota_exceeded | 429 | The account has reached its plan’s cap for the day or the month (Lagos time) — or, rarely, our own shared sending limit; the message says which. | Wait for the seconds in retry-after, or move to a larger plan. |
domain_not_verified | 403 | The from address’s domain is not verified on this account. | Finish the domain’s DNS records under Domains, or send from a verified domain. |
account_paused | 403 | Sending is paused on this account. | The dashboard says why. Email us if you think it is a mistake. |
internal_error | 500 | Something failed on our side. | Try again in a moment. If it keeps happening, write to us with the x-request-id. |
What to send again
rate_limited,quota_exceededandinternal_errormay succeed later: wait asretry-aftersays, then send again with the sameIdempotency-Key, so a request that did get through is not sent twice.- A network error or a timeout leaves you not knowing: send again with the same key — the first answer comes back if the first request arrived.
- Every other error needs a change to the request first.