Errors
HTTP status codes and the full error-code reference: what each means and how to fix it.
Every error returns a non-2xx status and a JSON body with a stable machine code.
Branch on error.code — the codes are stable; the messages may change. The
error envelope is always:
json
{ "error": { "message": "Human-readable explanation.", "code": "machine_code" } }HTTP status codes
| Status | Meaning | When |
|---|---|---|
200 | OK | Request succeeded (reads, updates). |
201 | Created | A new resource was created. |
202 | Accepted | Send/queue accepted for processing. |
400 | Bad Request | Invalid JSON or failed validation. |
401 | Unauthorized | Missing, invalid, or revoked key. |
403 | Forbidden | Scope, suspension, or sender/domain block. |
404 | Not Found | No such resource in this project. |
409 | Conflict | Suppressed address or duplicate. |
429 | Too Many Requests | Rate limit or send-quota exceeded. |
500 | Server Error | Unexpected error on our side. |
502 | Bad Gateway | Upstream email provider failed. |
Error code reference
| Code | HTTP | What it means | How to fix it |
|---|---|---|---|
unauthorized | 401 | No key was sent, or it's wrong, revoked, or doesn't start with m123_. | Send Authorization: Bearer m123_…. If revoked, create a new key. |
insufficient_scope | 403 | A sending-only key was used on an endpoint that needs full access. | Use a Full access key for that endpoint. |
suspended | 403 | The project this key belongs to is suspended. | Contact support — sending and management are paused. |
forbidden | 403 | The from isn't on a verified domain, the domain has an open deliverability issue, or auto-pause is active. | Verify your sending domain, resolve flagged DNS recommendations, then retry. |
validation_error | 400 | Invalid JSON, a missing required field, or a value that failed validation. | Read the message — it names the offending field — and correct the request. |
not_found | 404 | No contact, campaign, or template with that id exists in this project. | Check the id and that it belongs to the same project as the key. |
conflict | 409 | The address is suppressed, or another contact already uses that email. | Don't re-send to suppressed addresses; update the existing contact instead. |
rate_limit_exceeded | 429 | More than 10 requests per second were made with this key. | Back off and retry after the seconds in the Retry-After header. |
quota_exceeded | 429 | Your plan's daily or monthly send limit is used up. | Wait for the window to reset, or upgrade your plan. |
send_failed | 502 | The upstream email provider rejected or failed the send. | Retry; if it persists, check the message and your sender configuration. |
internal_error | 500 | An unexpected error on our side. | Retry with backoff. If it keeps happening, contact support. |