Email error codes
Email acceptance errors, HTTP statuses, retry guidance, and post-acceptance failure reasons.
This page lists email acceptance errors and post-acceptance failure reasons. Success requires both HTTP 202 and code=000000; acceptance does not mean delivery.
Acceptance errors
Use the HTTP status and six-digit code to decide what to do. Keep the traceId for support; do not branch on the human-readable message.
On failure, data=null. message is dynamic and should not be the only decision criterion.
| HTTP | code | Meaning and action |
|---|---|---|
| 400 | 010001 | Malformed JSON or request body. |
| 400 | 010002 | A required non-idempotency header is missing. |
| 400 | 010003 | Field, business parameter, or X-Custom-TraceId validation failed. |
| 400 | 010013 | Idempotency key is missing or invalid. |
| 405 | 010009 | HTTP method not supported. |
| 415 | 010010 | Content-Type not supported. |
| 401 | 020001 | AppID or API Key is missing. |
| 401 | 020002 | API Key is invalid, unknown, or disabled. |
| 401 | 020008 | Signature headers are incomplete, the signature is wrong, or Nonce was replayed; regenerate and check credentials. |
| 401 | 020009 | CurTime has a valid format but is outside the window; synchronize the clock and re-sign. |
| 403 | 020005 | Egress IP is not allowed or the allowlist configuration is invalid. |
| 409 | 010007 | The idempotency key maps to different content; stop automatic retries. |
| 409 | 010008 | The original task is still processing; use limited backoff with the original key and body. |
| 403 | 030003 | API Key daily quota reached. |
| 429 | 040001 | Short-term rate exceeded; honor Retry-After. |
| 500 | 050001 | Platform internal error or another unmapped acceptance exception. |
| 503 | 050002 | Service temporarily unavailable; limited retries can use the original key and body. |
| 504 | 050003 | Acceptance outcome unknown; reconcile the original task instead of using a new key. |
Post-acceptance failures
send_failed events can use these platform codes. Original provider reasons are separate from this table.
| Code | Meaning | Code | Meaning |
|---|---|---|---|
141001 | Template unavailable | 141010 | Message policy rejected |
141002 | Template body empty | 141011 | Invalid route configuration |
141003 | Transactional template variable missing | 141012 | Invalid channel configuration |
141004 | No route available | 141013 | Channel authentication failed |
141005 | MIME assembly failed | 141014 | Invalid runtime snapshot |
141006 | Channel explicitly rejected | 141015 | Invalid unsubscribe configuration |
141007 | Payload cannot be parsed | 141016 | Retries exhausted |
141008 | All recipients suppressed | 141017 | Internal processing failed |
141009 | Sender domain unauthorized | 141018 | No valid recipients |
These are post-acceptance failures and must be handled separately from HTTP acceptance errors. See Send API.
How to respond
For rate limits, wait at least Retry-After. After a timeout, connection loss, or 5xx, reconcile the original task before a limited retry with the same X-Idempotency-Key and body. Do not automatically submit a new task for a per-message failure after acceptance.
See the error overview for the shared response format and other product ranges.
Last updated on