Error codes and rate limits
Errors look like:
{"error": {"code": "domain_not_verified", "message": "domain acme.com is not verified", "param": "from", "request_id": "req_…"}}
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_json |
Body is not valid JSON |
| 401 | invalid_api_key |
Missing, unknown, revoked or expired key |
| 403 | insufficient_scope |
Send-only key used on a full-scope endpoint |
| 403 | domain_not_allowed |
Key is restricted to another domain |
| 403 | org_paused / org_suspended |
Sending is paused or the account is suspended |
| 404 | not_found |
Unknown ID |
| 409 | idempotency_conflict |
Same key, different body |
| 413 | payload_too_large |
Request or message too big |
| 422 | validation_error |
Invalid field (see param) |
| 422 | domain_not_verified |
From domain not verified |
| 422 | all_recipients_suppressed |
Nothing left to send |
| 429 | rate_limited |
Slow down; see Retry-After |
| 429 | quota_exceeded |
Monthly quota used |
| 500 | internal_error |
Our fault; quote the request_id |
Rate limits
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 includes Retry-After (seconds). API requests are limited to 20 per second per key (burst 100). Sending is limited per organization (default 14 recipients per second); new accounts are limited to 2 per second and 500 emails per day for the first week.