123eworld Knowledge Hub → SMS API → Page 309
SMS API Delivery Failure Analysis: Temporary vs Permanent SMS Failures
A practical developer reference designed to solve real implementation and production problems around sms api delivery failure analysis: temporary vs permanent sms failures.
Why failures need classification
Not every SMS failure should trigger the same action. A temporary provider timeout may justify retry or reconciliation, while an invalid destination may be permanently undeliverable.
Temporary failures
Temporary failures can include provider timeouts, throttling, transient network errors or temporary carrier conditions. Retry policy should be bounded and based on evidence.
Permanent failures
Invalid numbers, unsupported destinations or certain rejection codes may be permanent. Repeatedly retrying these wastes capacity and can increase cost.
Expired messages
A message can become irrelevant before a provider returns a terminal receipt. Expiry should be a distinct business state when appropriate.
Provider versus carrier failure
Separate failure origin where possible. Provider API rejection is operationally different from a carrier delivery rejection.
Error normalization
Map provider and carrier codes into stable categories such as invalid_destination, provider_unavailable, throttled, expired or unknown.
Failure analytics
Track failure rate by provider, destination country, sender, application, route and reason.
Root-cause analysis
Look for correlated changes rather than treating every failed SMS independently. A sudden rise in one country may indicate route or carrier issues.
Retry effectiveness
Measure how many retried messages eventually deliver. Retrying everything is not an optimization.
Customer reporting
Explain failures in developer-friendly terms while retaining detailed diagnostics for support.
Testing
Build a failure matrix with expected action: retry, reconcile, fail permanently, alert or escalate.
Reference workflow
Receipt → classify → update state → decide retry/reconciliation → record evidence → notify/report.
Practical implementation guidance
Design the public API around a stable logical message ID and keep provider-specific complexity behind internal adapters. Every asynchronous step should be durable, observable and safe to retry.
Security and privacy
Treat phone numbers, message content, credentials and delivery evidence as sensitive. Apply tenant authorization before data access and avoid unnecessary values in logs, traces and reports.
Developer-first principle
A useful reference page should tell developers not only what a feature is, but how to implement it safely, how to troubleshoot it and what failure cases to expect.
Related 123eworld guides
Explore the 123eworld SMS & WhatsApp Knowledge Hub for related API, routing, reliability and developer guides.
Failure decision tree
Start with the evidence source: API validation, provider submission, provider receipt or internal timeout. Then classify the failure. This prevents a validation error from entering a provider retry loop or a provider timeout from being treated as a permanent rejection.
Retry window
Define how long temporary failures may be retried. A message that is time-sensitive may need a shorter window than a routine notification. Retry policy should be configurable by message class where business requirements justify it.
Failure reason taxonomy
Use stable categories such as invalid_destination, sender_rejected, provider_throttled, provider_unavailable, carrier_failed, expired and unknown. Keep raw provider codes separately.
Destination analysis
Track failures by country and carrier where available. A sudden rise in one destination may indicate a route issue rather than a problem with customer data.
Template analysis
If failures correlate with one template, sender or message class, inspect content and registration requirements. Avoid assuming that all failures are infrastructure failures.
Retry effectiveness
Measure recovery rate after retry. If 2% of messages recover after retry but 80% of retry attempts target permanent failures, the policy needs improvement.
Support diagnostics
A support view should show logical message ID, attempt history, provider, route, timestamps and normalized reason. This is more useful than a single 'failed' label.
Customer-facing reason
Return a stable, understandable reason where appropriate, but avoid exposing sensitive provider internals or security information.
Alerting
Alert on unusual failure-rate changes rather than individual failures. Segment alerts by provider and destination to identify localized incidents.
Failure review
After an incident, review whether failures were classified correctly and whether retry behaviour increased or reduced impact.
Failure correlation
Compare failure rates against provider response latency, route configuration changes, sender changes and destination patterns. Correlation often identifies whether the failure is operational, configuration-related or destination-specific.
Unknown failures
Unknown should be a temporary operational classification, not a permanent wastebasket. Alert when unknown volume exceeds a small baseline and require classification for recurring codes.
Retry cost
Calculate the physical segment volume generated by retries. A retry policy that improves delivery by a small amount can still create significant additional cost if it repeatedly resubmits long messages.
Failure feedback loop
Use failure analysis to improve validation and routing. If a large share of failures comes from invalid destinations, improve input validation. If failures are route-specific, adjust provider health policy.
Failure trend baselines
Maintain normal failure baselines by provider and destination. An absolute 2% failure rate may be normal for one traffic class and alarming for another. Use comparable populations.
Permanent failure prevention
Move preventable failures upstream. Validate phone number format, sender eligibility and known destination restrictions before provider submission where the platform has reliable rules.
Retry suppression
When a provider returns a clearly permanent code, mark the attempt terminal and do not consume secondary-provider capacity unless the routing policy explicitly permits an alternative route.
Post-incident analysis
Separate infrastructure failures from recipient-level failures in incident reports. Only the former should normally drive provider availability decisions.
Failure troubleshooting checklist
Identify the failure source, normalize the reason, determine retryability, inspect previous attempts and compare the failure with provider and destination baselines. This avoids repeated retries that cannot improve the outcome.
Reference principle
Failure analysis should produce a decision—retry, route differently, correct data, expire, alert or investigate—not merely a more detailed failure label.
Advanced production guidance
Failure analysis should feed directly into route-health decisions. If one provider produces a sudden increase in provider-unavailable errors while another remains healthy for the same country and traffic class, the routing system may reduce the first provider's eligibility. However, recipient-level failures such as invalid numbers should not normally reduce provider health. This distinction is important because a provider should not be penalized for failures caused by customer data. Maintain separate operational, destination and content-related failure categories so health algorithms can use the right signals. Over time, this classification also becomes valuable for commercial reviews, customer onboarding and API validation improvements.
Reference architecture detail
A failure taxonomy should be reviewed whenever a new provider is added. Do not allow each provider adapter to invent its own retry categories. The normalization layer should translate new provider codes into the common taxonomy and preserve the original code for diagnostics. This creates a consistent operational language across providers. It also allows the platform to compare providers fairly. If one provider reports a failure as 'temporary unavailable' and another reports 'gateway timeout', both can be mapped to the same operational category while their raw evidence remains available for engineering investigation.
Final production checklist
Use failure categories as an engineering feedback loop. If invalid destinations dominate, improve validation. If throttling dominates, review rate limits and provider capacity. If unknown errors dominate, improve provider normalization. If delivery failures cluster by country, investigate routing. This keeps failure analytics connected to concrete product improvements.
Advanced reference note
A failure analysis system should distinguish 'message failed' from 'attempt failed'. A primary provider attempt can fail while a secondary route successfully delivers the same logical message. Customer-facing reporting should normally show the final logical outcome, while internal analytics should preserve each attempt. This distinction makes failover measurable without overstating customer-visible failures. It also lets engineering calculate provider reliability independently from overall messaging reliability. When a provider has many failed attempts but another route recovers most messages, the platform can see both the provider weakness and the successful customer outcome.
Final reference guidance
Use historical failure data to tune retry windows periodically. If temporary failures almost always recover within a few minutes, a longer retry window may add little value. If certain message classes are time-sensitive, their retry policy should reflect that business requirement rather than using one global rule.
Implementation safeguard
A failure dashboard should also distinguish failures before submission from failures after provider submission. The first category often points to validation, routing or provider-API problems; the second can indicate carrier or destination issues. This distinction makes corrective action much faster.