API errors
Every error response has error.code and error.message; a 429 for a sending limit also has error.reason and, when waiting helps, Retry-After. See the API reference.
| Code | Status | What it means | What to do | Repeat |
|---|---|---|---|---|
invalid_request |
400 | The request is malformed or has unknown fields. | Fix the request body or query. | After fixing the request |
unauthorized |
401 | The API key is missing, wrong, revoked or expired. | Use a current API key. | After fixing the request |
account_suspended |
403 | Your organization is suspended. | Contact support. | Will not succeed |
activation_inactive |
403 | Sending is not activated for this deployment. | Contact support. | Will not succeed |
activation_scope_mismatch |
403 | The key is outside the activated sending scope. | Use a key for the activated project and stream. | After fixing the request |
customer_grant_required |
403 | This sender has no sending permission. | Finish domain setup or contact support. | Will not succeed |
customer_price_authority_required |
403 | Your plan does not currently authorize sending. | Contact support. | Will not succeed |
customer_stream_paused |
403 | Sending on this stream is paused for review. | Contact support; customers cannot lift this pause. | Will not succeed |
environment_mismatch |
403 | This endpoint needs a test API key; a live key cannot read captured test mail. | Use a test API key for /v1/test endpoints. | After fixing the request |
forbidden |
403 | The API key lacks the scope this action needs. | Use a key with the required scope. | After fixing the request |
recipient_not_allowlisted |
403 | The recipient is not allowed in this mode. | Use an allowed recipient. | After fixing the request |
sender_not_activated |
403 | The sender is not the activated identity. | Send from the activated sender. | After fixing the request |
not_found |
404 | The resource does not exist or is not visible to this key. | Check the ID and the key’s project. | Will not succeed |
idempotency_conflict |
409 | The Idempotency-Key was already used with different content. | Use a new key for new content; never reuse a key for a different message. | After fixing the request |
too_late_to_cancel |
409 | The message was already handed over or finished. | Read the message status; it cannot be recalled. | Will not succeed |
content_too_large |
413 | Subject or body exceeds the size limit. | Shorten the content. | After fixing the request |
request_too_large |
413 | The request exceeds the size limit. | Send a smaller request. | After fixing the request |
customer_payload_limit |
422 | The message exceeds your configured size limit. | Send a smaller message. | After fixing the request |
feature_not_enabled |
422 | A requested field is not supported yet. | Remove the unsupported field. | After fixing the request |
identity_not_authorized |
422 | The stream or sender is not authorized for this key. | Use the stream and sender shown with your key. | After fixing the request |
invalid_expiry |
422 | expires_at must be within the next 24 hours. | Choose a valid expiry. | After fixing the request |
invalid_mailbox |
422 | An email address is not valid. | Correct the address. | After fixing the request |
invalid_page_size |
422 | The requested page size is out of range. | Use a supported page size. | After fixing the request |
invalid_subject |
422 | The subject contains control characters. | Remove control characters. | After fixing the request |
activation_cap_reached |
429 | The activation sending limit was reached. | Contact support. | Will not succeed |
customer_grant_cap_reached |
429 | A limit on this sender’s permission was reached; error.reason names it. | Follow Retry-After when present and repeat with the same Idempotency-Key; without it, contact support. | Same key and body |
customer_proof_cap_reached |
429 | One of your sending limits was reached; error.reason names it. | Follow Retry-After when present and repeat with the same Idempotency-Key; without it, contact support. | Same key and body |
customer_shared_cap_reached |
429 | The service reached a shared limit (error.reason service_capacity). | Follow Retry-After and repeat with the same Idempotency-Key. | Same key and body |
quota_exceeded |
429 | A sending limit was reached. | Wait for Retry-After and repeat with the same Idempotency-Key. | Same key and body |
test_allowance_exceeded |
429 | The test allowance for captured mail was reached; error.reason names the cap. | Wait for Retry-After and repeat with the same Idempotency-Key; captures expire after seven days. | Same key and body |
service_unavailable |
503 | Temporarily unavailable, or the outcome of your request is uncertain. | Repeat with the same Idempotency-Key and body; it returns the original result if it was accepted. | Same key and body |