Skip to content
Invitation-only alpha. Features and limits may change as we learn from testing.

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