123eworld Knowledge Hub → Transactional SMS API → Page 282
Transactional SMS API Status Codes: Normalizing Provider Responses for Developers
A practical developer reference designed to solve real implementation, integration and production problems around transactional sms api status codes: normalizing provider responses for developers.
Why normalization matters
Provider codes are inconsistent. One provider may use numeric status codes, another may use text, and another may report several intermediate states. Developers need a stable platform vocabulary.
Canonical states
A practical model can distinguish accepted, queued, submitted, delivered, failed, expired, rejected and unknown. Keep the model small enough to remain predictable.
Temporary versus permanent
Error normalization should indicate whether the customer should retry, correct configuration or wait for delivery processing.
Raw evidence
Never throw away the original provider code, message and timestamp. Normalization is a compatibility layer, not a replacement for evidence.
Mapping versions
Provider mappings can change as providers add new codes. Version the mapping logic and retain enough information to reconstruct historical interpretations.
HTTP response mapping
API responses should distinguish client errors, authentication failures, rate limiting, temporary platform errors and accepted asynchronous work.
Webhook status mapping
Inbound delivery events should pass through the same normalized status model used by reporting.
Unknown codes
Unknown provider codes should enter a safe state and alert operations rather than being silently classified as delivered.
Developer documentation
Publish examples showing how canonical status and error fields should be interpreted.
Testing
Use contract tests for every provider code and regression tests when mappings change.
Reference flow
Raw provider response → adapter mapping → canonical status/error → state machine → API/reporting/webhook.
Operational checklist
Monitor unknown-code rate, mapping changes and provider-specific failure trends.
Architecture principle
Keep synchronous API handling small and deterministic. Authenticate, authorize, validate and persist the logical message before handing delivery work to asynchronous processing. This keeps provider latency out of the customer request path and creates a stable foundation for retries and reconciliation.
Security principle
Tenant isolation, least privilege, encrypted transport, protected credentials and careful logging apply to every layer. Operational convenience should never become a reason to expose phone numbers, message content or secrets unnecessarily.
Developer experience
Documentation should explain the exact difference between accepted, submitted and delivered. Provide stable identifiers, canonical statuses, retry guidance, examples and failure scenarios so developers can build correct integrations without reverse-engineering provider behaviour.
Production testing
Test the unhappy paths deliberately: timeouts, duplicates, provider outages, throttling, worker crashes, delayed receipts, malformed callbacks and configuration changes. Reliability is demonstrated by controlled failure testing, not only by successful sends.
Operational checklist
Before production, verify durable storage, idempotency, queue behaviour, provider capacity, receipt processing, monitoring, alerting, data protection, reconciliation and recovery procedures.
Related knowledge
For additional implementation guidance, use the 123eworld SMS & WhatsApp Knowledge Hub and the related pages in this master project.
Canonical error model
Use a stable error object containing a platform code, human-readable message, retryability indicator and correlation ID. Avoid exposing raw provider messages as the primary developer contract.
Provider mapping table
Maintain a versioned mapping table with provider name, raw code, canonical state, retryability and operational meaning. Review new unknown codes as part of provider onboarding and incident analysis.
Status transition rules
Normalization must happen before the message state machine applies an event. This prevents provider-specific strings from leaking into business logic.
Backward compatibility
When adding a new canonical state, consider existing SDKs and customer applications. Prefer additive changes and document how older clients should interpret new values.
Unknown-state handling
An unknown code should never be mapped to delivered merely because it is not recognized as a failure. Safe ambiguity is better than false success.
Support tooling
Show both canonical status and raw provider evidence to authorized operators. This gives developers a stable API while preserving the detail required for telecom troubleshooting.
Deep production guidance
Status normalization should be treated as part of the public API contract. Developers should not need to learn the private status vocabulary of every SMS provider connected to the platform. Define canonical states and document their meaning, terminality and expected client action. For example, accepted may mean the platform has durably created the message, while submitted means a provider accepted the downstream submission. Delivered should only be used when the platform has received the evidence required by its delivery semantics. Unknown should be a legitimate state rather than an error that gets silently discarded. Provider mappings should be tested whenever a new route is onboarded and whenever the provider changes its documentation or behaviour. Store raw provider code, text, timestamp and adapter version with the event so a future mapping correction can be applied. If a provider introduces a new code that the platform does not recognize, alert operations and preserve the message in a safe state. Never default unknown to delivered. A false positive delivery result is more damaging than a temporary unknown state because it can cause business systems to stop retrying or to falsely confirm a customer transaction.
Implementation and troubleshooting note
Status normalization should cover both synchronous API errors and asynchronous delivery outcomes. A developer should be able to understand why a request was rejected, why a message is waiting, and why a delivered message later has diagnostic events without learning provider-specific codes. Document terminal states carefully. If a status is terminal, clients should not keep polling indefinitely. If a status is temporary, explain whether the platform will retry automatically or whether the client must act. Clear semantics reduce unnecessary support cases and prevent integrations from implementing unsafe retry loops.
Production validation
Canonical statuses should be stable enough for SDKs and customer applications to depend on them. When a provider adds a new code, the platform can initially classify it as unknown while retaining the raw evidence. Engineering can then decide whether it represents an existing state or requires a new canonical state. This controlled process prevents provider changes from silently changing customer application behaviour. It also gives the platform a safe way to onboard new providers without expanding the public status vocabulary unnecessarily.
Quick troubleshooting checklist
Check canonical state, raw provider code, mapping version, transition validity, unknown-code alerts and developer-facing semantics.
Advanced design consideration
Canonical statuses should be included in SDKs and examples so developers do not build integrations around human-readable text. Machine-readable codes should remain stable, while descriptions can evolve. If a new status becomes necessary, introduce it deliberately with migration guidance. The API should also document whether status transitions are eventual and how long clients should reasonably poll before relying on webhooks or reconciliation. This makes the status model useful for both simple integrations and sophisticated enterprise workflows.
Final implementation guidance
The canonical status model should be published alongside examples for polling and webhooks. Developers who use polling need to know which states require another request and which states are final. Developers who use webhooks need to understand that events can be duplicated or delayed. Both interfaces should expose the same logical message state so a customer does not see one status through the API and another through the webhook for the same evidence. Consistency is more important than matching every provider-specific status.
Operational maturity note
Status normalization should be reviewed during provider onboarding. Before production, take representative provider responses and map each one to the canonical model. Include successful, temporary, permanent and ambiguous outcomes. Store the mapping as test data so future adapter changes cannot accidentally reinterpret a previously understood provider response.
Production documentation note
When a provider code is ambiguous, the platform should prefer a conservative classification and preserve the raw evidence. An unknown state can later be reprocessed after engineering confirms its meaning. False delivery is much harder to correct because downstream applications may already have acted on it. This is why normalization must favour correctness over optimistic reporting.
Closing principle
Keep canonical status names stable and use separate diagnostic fields for provider-specific detail. This lets SDKs remain simple while operations retain the evidence needed for investigations.