SMS error codes
SMS pre-acceptance validation (100xxx) and post-acceptance delivery result (101xxx) codes, adjacent shared codes, and legacy code notes.
This page lists the platform error codes used by the SMS API. All business codes are six-digit strings; 000000 means the operation itself succeeded. For SMS submission, success means accepted, not delivered. Read the final delivery result from the query API or callback.
This page follows the SMS section of the review specification: use 100xxx for submission validation and 101xxx for delivery results. Always match the complete six-digit code; the prefix identifies the catalog area only and does not determine retry behavior or acceptance status.
Code ranges
| Range | Area | Meaning |
|---|---|---|
010xxx | Request and resource | Parameters, formats, resource state, and idempotency conflicts. |
020xxx | Identity and access | API keys, permissions, IP rules, accounts, and authentication. |
030xxx | Billing and quota | Balance, credit, period quota, and pricing configuration. |
040xxx | Rate and concurrency | Request rate, submission rate, and concurrency limits. |
050xxx | Platform service | Internal failures and unknown request outcomes. |
100xxx | SMS submission validation | Rejected before acceptance; fix the request or account configuration. |
101xxx | SMS delivery result | Per-message result after acceptance; read it from the query result or callback data. |
06xxx–09xxx | General reserved | Assigned centrally after approval. |
90xxx–99xxx | Not allocated | Reserved for future expansion. |
Common errors
The SMS API may also return codes from the common ranges. Use the range page for the full list and handling guidance:
010xxx— Request and resource020xxx— Identity and access030xxx— Billing and quota040xxx— Rate and concurrency050xxx— Platform service
For a 429 or a temporary 503, wait for Retry-After when present; otherwise use bounded exponential backoff. Do not create a new SMS request until the original outcome is known.
SMS submission validation (100xxx)
A 100xxx result means the request was not accepted. Fix the cause, then submit a new request.
| Code | Name | Customer action | Retry |
|---|---|---|---|
100001 | Sender not registered | Complete sender registration. | Fix and resubmit |
100002 | Template not available | Use an approved, active template. | Fix and resubmit |
100003 | Sending method not supported | Use a supported sender or method. | Fix and resubmit |
100004 | Content not allowed | Revise the content according to the published rule. | Fix and resubmit |
100005 | Sender not authorized | Use an authorized sender. | Fix and resubmit |
100006 | Destination not enabled | Check the destination scope or request access. | Fix and resubmit |
100007 | Content does not match template | Generate the content from the approved template. | Fix and resubmit |
100008 | SMS segments exceed limit | Shorten the content or adjust the character set. | Fix and resubmit |
100009 | Recipient opted out | Stop sending and follow the consent process. | Do not automatically resend |
100010 | Outside allowed sending window | Wait for the allowed window and check message validity. | Wait and retry |
100011 | No SMS route available | Try later; contact support if it continues. | Wait and retry |
Number or sender format errors use 010003. A valid but unregistered sender uses 100001. Do not infer a content violation unless the response provides that reason.
SMS delivery result (101xxx)
A 101xxx code describes the result of an accepted message. It appears in the query result or callback data, not as the HTTP error of the send request.
| Code | Name | Customer action | Retry |
|---|---|---|---|
101001 | Invalid recipient number | Check and update the number. | Do not automatically resend |
101002 | Recipient temporarily unreachable | Decide whether to send again within the business validity window. | Do not automatically resend |
101003 | Carrier rejected | Review destination requirements and contact support if needed. | Do not automatically resend |
101004 | Not confirmed delivered within validity | Mark the result as unknown; do not assume the message was not received. | Do not automatically resend |
101005 | Content blocked downstream | Review the content and destination requirements. | Do not automatically resend |
101006 | Sender rejected downstream | Check registration and allowed scope. | Do not automatically resend |
101007 | Downstream capacity limit | Adjust future sending rate and evaluate a new message. | Do not automatically resend |
101008 | Downstream network failure | Monitor recovery and decide whether to send again. | Do not automatically resend |
101009 | Recipient refused | Stop sending and record the refusal. | Do not automatically resend |
101010 | Expired before sending | Check validity, queueing, and sending volume. | Do not automatically resend |
101011 | Platform execution failed | Keep the message ID and traceId and contact support. | Do not automatically resend |
101012 | Delivery failed, reason unknown | Keep the message ID and contact support. | Do not automatically resend |
101004 means the delivery outcome is unknown; 101012 means delivery failed but the reason is unknown. A new send is a new business operation and may create another charge.
Handling rules
000000means the API operation succeeded. For submission, it only means the request was accepted.- A successful query can still contain a failed message. In that case the outer
coderemains000000and the failure is indata.errorCode. - For
100xxx, fix the request or account configuration before resubmitting. - For
101xxx, do not automatically resend. Decide based on the business validity window and the delivery result. - For an undocumented code, log
code,message, andtraceId, stop automatic retries, and contact support.
Related
Last updated on