SMS Error Codes

A complete reference of the errors returned by the SMS API, including HTTP request errors and per-message delivery failure codes. Use these codes to build robust retry logic and clear user-facing messaging.

🧱 Error Response Format

All API errors share a consistent shape:

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "The 'to' field is not a valid E.164 number",
    "details": { "field": "to" },
    "timestamp": "2026-05-28T10:30:00Z"
  }
}

Field	Description
code	Stable machine-readable error code
message	Human-readable explanation
details	Optional contextual data (e.g. offending field)
timestamp	When the error occurred (ISO 8601)

🌐 HTTP Status Codes

HTTP	Meaning
200	Success
400	Bad request — invalid or missing parameters
401	Unauthorized — missing or invalid API key
402	Payment required — insufficient balance
404	Not found — unknown message_id
422	Unprocessable — request valid but cannot be fulfilled
429	Too many requests — rate limit exceeded
500	Internal server error

🚫 Request Error Codes

Returned synchronously when a POST/GET request cannot be accepted.

Code	HTTP	Description	Resolution
INVALID_PHONE	400	to is not valid E.164	Include the country code, e.g. +251911234567
INVALID_SENDER_ID	400	from is malformed	Use 3-11 alphanumeric characters
SENDER_ID_NOT_APPROVED	422	Sender ID not yet approved	Register and await approval — see Sender IDs
MESSAGE_TOO_LONG	400	text exceeds 1600 chars	Shorten the message
MISSING_PARAMETER	400	A required field is absent	Check details.field
BATCH_TOO_LARGE	400	More than 1,000 messages	Split into smaller batches
UNAUTHORIZED	401	Bad or missing API key	Verify your Authorization header
INSUFFICIENT_BALANCE	402	Account balance too low	Top up your account
MESSAGE_NOT_FOUND	404	Unknown message_id	Confirm the ID returned at send time
RATE_LIMITED	429	Exceeded 100 req/sec	Back off and retry
INTERNAL_ERROR	500	Unexpected server error	Retry; contact support if it persists

📭 Delivery Failure Codes

Returned asynchronously via Delivery Reports as the error_code when a message reaches failed status.

Code	Description	Resolution
DLR_INVALID_NUMBER	Number does not exist or is unreachable	Validate the recipient
DLR_ABSENT_SUBSCRIBER	Handset off or out of coverage	Retry later
DLR_REJECTED_OPERATOR	Operator blocked the message	Check sender ID / content compliance
DLR_BLOCKED_CONTENT	Message flagged as spam	Review content and templates
DLR_DND	Recipient on a do-not-disturb list	Respect opt-outs
DLR_EXPIRED	Validity period elapsed before delivery	Resend
DLR_PORTED_NUMBER	Routing failed after number port	Retry; contact support if persistent

🔁 Recommended Retry Strategy

async function sendWithRetry(payload, attempt = 0) {
  const res = await sendSMS(payload);
  if (res.ok) return res;

  const { code } = (await res.json()).error;

  // Retry only on transient errors
  if (['RATE_LIMITED', 'INTERNAL_ERROR'].includes(code) && attempt < 5) {
    const delay = Math.min(2 ** attempt * 200, 5000); // exponential backoff
    await new Promise(r => setTimeout(r, delay));
    return sendWithRetry(payload, attempt + 1);
  }

  throw new Error(`SMS failed: ${code}`);
}

import time

TRANSIENT = {"RATE_LIMITED", "INTERNAL_ERROR"}

def send_with_retry(payload, attempt=0):
    res = send_sms(payload)
    if res.ok:
        return res
    code = res.json()["error"]["code"]
    if code in TRANSIENT and attempt < 5:
        time.sleep(min(2 ** attempt * 0.2, 5))
        return send_with_retry(payload, attempt + 1)
    raise RuntimeError(f"SMS failed: {code}")

💡 Best Practices

• Branch on code, not message — messages may change, codes are stable.
• Retry only transient errors (RATE_LIMITED, INTERNAL_ERROR) with backoff.
• Treat 4xx as permanent — fix the request rather than retrying.
• Log timestamp and details to speed up support investigations.

📚 Related Resources

• Send SMS
• Bulk SMS
• Delivery Reports
• Sender IDs

---

Last Updated: May 2026 · Need help? Contact Support →