SMS API Error Codes and Support Runbook: A Practical Guide

The short version

When an SMS fails, your support team needs more than a generic "delivery failed" message. They need to know what the error means, whether to retry, and when to escalate. This runbook maps the most common SMS API error codes you'll encounter with Notilify and other transactional SMS providers into clear support workflows—so your team can resolve delivery issues faster and with confidence.

• Error codes fall into three buckets: provider-level, carrier-level, and number-specific failures—each requires different handling
• Webhook payloads include delivery state, error codes, and retry timestamps that your support team can query directly
• Not all errors warrant retries; understanding idempotency keys prevents duplicate sends and frustrated users
• Certain errors signal sender identity problems that require upstream fixes before retrying will work
• Support visibility into routing decisions and carrier responses reduces back-and-forth with users

SMS API Error Codes by Category

Provider-level errors occur before the message reaches the carrier network. These typically indicate configuration issues or API misuse. Common codes include 4001 (invalid payload), 4002 (missing required field like sender_id or recipient), 4003 (rate limit exceeded), and 4004 (authentication failure). When your support team sees these, the issue is usually in your integration code or API credentials—not the carrier.

Carrier-level errors come back from the downstream networks after submission. These are where observability matters most. The most common carrier rejections include 5001 (invalid destination format—wrong number of digits or country code), 5002 (number not allocated—the line doesn't exist), 5003 (temporary network failure—carrier temporarily unable to route), and 5004 (permanent delivery failure—the number is permanently unavailable).

Number-specific errors target individual recipients. Error 6001 means the number is on a carrier blocklist; 6002 indicates the subscriber has opted out of your sender ID; 6003 signals possible fraud or pumping behavior triggering carrier filters. These often require checking your sender ID registration status or reviewing your sending patterns.

Support Runbook: From Error to Resolution

• Step 1: Pull the message ID and check the webhook delivery payload. Identify whether the error is provider-level, carrier-level, or number-specific. Provider errors mean fix your code or config; carrier errors mean check the recipient number or retry later; number-specific errors may require sender ID changes or user contact.
• Step 2: For rate limit errors (4003), implement exponential backoff in your code. Your team should not manually retry—build it into your retry logic using the idempotency key to avoid duplicates. Wait at least 60 seconds before the first retry, then scale exponentially.
• Step 3: For invalid number errors (5001, 5002), verify the number format includes the correct country code. If the format is correct but you're getting rejections, check whether the number type is supported in your pricing tier—some countries require premium routes.
• Step 4: For carrier-level timeouts (5003), retry after 5-10 minutes. If you see repeated 5003 errors for a specific carrier, that's a routing issue your provider should investigate. Document the pattern and timestamp for escalation.
• Step 5: For blocklist or opt-out errors (6001, 6002), do not retry without investigation. Check your sender ID registration status and verify the user hasn't opted out. If you're using a new sender ID, carriers may be filtering messages until registration propagates—typically 24-72 hours.
• Step 6: Use the Notilify dashboard delivery timeline to trace each message. Your support team can see exactly where in the pipeline the failure occurred, what the carrier returned, and whether previous delivery attempts were made.

Make Error Codes Operational, Not Ambiguous

The difference between a support team that can resolve SMS issues and one that can't often comes down to having concrete error definitions and clear next steps. When your support operators understand that a 5002 error means the number doesn't exist and they should verify the user's phone number, not retry the same message, they close tickets faster and avoid frustrating users with duplicate deliveries.

Build these error codes into your internal dashboards, document them in your support wiki, and ensure your team knows which errors warrant retry, which require investigation, and which need escalation to engineering. Delivery failures won't disappear, but your team's response time can shrink dramatically when error codes become actionable instead of ambiguous.