123eworld Knowledge Hub → SMS API → Page 302
SMS API Error Handling: Error Codes, Retryable Failures and Developer-Friendly Responses
A practical developer reference designed to solve real implementation and production problems around sms api error handling: error codes, retryable failures and developer-friendly responses.
Why error design matters
An API error should tell a developer what happened and what action is appropriate. Raw provider codes are rarely enough because they vary by vendor.
Error categories
Use stable categories such as validation_error, authentication_error, authorization_error, rate_limited, temporary_failure and permanent_failure.
HTTP status versus business code
HTTP status communicates transport-level outcome, while a machine-readable application code explains the messaging-specific reason. Keep both consistent.
Retry guidance
Errors should make retryability explicit. A temporary provider failure may be retried by the platform, while invalid sender configuration should not be retried automatically.
Validation errors
Return field-level information for malformed phone numbers, missing sender IDs, invalid message content or unsupported options.
Provider normalization
Translate provider-specific failures into canonical categories while retaining raw diagnostic codes in protected internal records.
Correlation IDs
Every error response should include a request or correlation ID so support teams can find the relevant server-side evidence.
Avoid sensitive leakage
Do not return credentials, provider secrets, internal stack traces or unnecessary customer data in error messages.
Consistency
Use the same error structure across send, status, reports and webhook configuration APIs.
Testing
Build contract tests for every documented error category and representative provider failures.
Reference structure
HTTP status + stable error code + message + correlation ID + optional field details + retry guidance.
Developer experience
Documentation should show both successful and failed examples so developers can implement correct handling.
Security and privacy
Treat phone numbers, message content, credentials and delivery data as sensitive operational information. Avoid unnecessary logging and ensure tenant authorization is applied before data access.
Production reliability
Design for timeouts, duplicates, retries, provider failures and delayed events. A messaging platform is asynchronous infrastructure, so success-path testing alone is insufficient.
Developer-first principle
The public API should hide unnecessary telecom complexity while exposing enough structured information for developers to build correct integrations.
Related 123eworld guides
Explore the 123eworld SMS & WhatsApp Knowledge Hub for related developer, API, routing and production guides.
A useful error taxonomy
Define a small, stable set of categories that map to developer actions. Validation errors require request correction. Authentication and authorization errors require credential or permission changes. Rate-limit errors require pacing. Temporary failures may be retried by the platform. Permanent delivery failures should not be retried automatically.
Error envelope
Use a consistent response shape such as error code, human-readable message, correlation ID and optional details. Keep the machine-readable code stable across API versions. Field-level details can identify invalid recipient or sender fields without revealing unrelated customer information.
Provider diagnostics
Store provider-specific status codes internally and expose them only where they provide real value. A raw telecom code is not a substitute for a canonical API error. Normalization lets customers migrate between providers without rewriting their application error handling.
Retryable versus non-retryable
Mark retryability explicitly in internal error classification. A timeout after provider submission is different from an invalid sender. The former may require reconciliation; the latter should be corrected before another attempt. This distinction prevents retry storms.
Correlation and support
Every error should carry a correlation ID or request ID. The support team can use it to locate validation, routing and provider evidence without asking the customer to provide sensitive message content. This also makes distributed tracing practical.
Contract testing
Maintain automated tests for documented error responses. Provider adapters should map representative provider failures into the canonical taxonomy. When a new provider code appears, classify it deliberately rather than allowing an unknown error to leak through the public API.
Error documentation
For every public error code, document meaning, typical cause, whether the platform retries automatically, what the developer should change and whether the request can safely be repeated. This transforms an error catalog into an implementation guide.
Validation details
Field errors should use stable field names and machine-readable reasons. For example, an invalid recipient should be distinguishable from an unsupported destination. This allows forms and integration middleware to correct data automatically.
Unexpected errors
For unclassified internal failures, return a generic server error and correlation ID. Log the detailed exception internally. Never expose stack traces or infrastructure names to customers.
SDK mapping
SDKs should map canonical error codes into documented exception classes. Applications can then catch a rate-limit exception separately from a validation exception without parsing message text.
Error examples
Documentation should show a successful request followed by common failure examples. For each failure, explain whether the developer should correct data, authenticate again, slow down, wait for platform recovery or contact support. This turns the API documentation into a troubleshooting guide.
Error localization
Human-readable messages can be localized or improved without breaking integrations if machine-readable codes remain stable. Developers should always branch on the code rather than message text.
Support escalation
A correlation ID should be sufficient for support to locate the relevant request and provider attempt. Customers should not need to send full message text or phone numbers in support tickets merely to identify a failed API call.
HTTP semantics
Use standard HTTP status classes consistently. Do not return 200 for a request that the API rejected simply because an error object is present in the body. Clients, proxies and SDKs rely on HTTP semantics.
Retry safety
Document whether the platform automatically retries a temporary error. If it does, a client should not blindly retry the same send without idempotency. Clear ownership of retry responsibility prevents duplicate traffic.
Versioned error contracts
When adding new error codes, keep existing codes stable and document new handling. SDKs can introduce new exception types in a major or minor release according to the compatibility policy.
Machine-readable details
Keep error codes short and stable, but allow optional structured details for advanced integrations. A validation error can contain a list of invalid fields, while a temporary provider failure can contain a safe retry recommendation.
Production runbooks
For every major error category, write an operator action. Authentication failures may require credential review; rate limits may require capacity or contract review; provider failures may require route investigation. This makes error design useful beyond the developer documentation.
Error compatibility
Once an error code is published, treat its meaning as part of the API contract. Improve human-readable text without changing the code's semantics. If a new distinction is required, add a new code rather than changing the old one unexpectedly.
Final error principle
Good errors reduce support demand because they tell developers what happened, whether retry is safe and what action should be taken.
Production implementation detail
Error handling should be designed alongside observability. When a developer receives a correlation ID, the platform should be able to locate the request across authentication, validation, routing, queue and provider layers. Distributed tracing or structured logs can connect these components without exposing message content. This turns a generic 'request failed' support conversation into a precise investigation of where the operation stopped.
Final developer checklist
For incident analysis, preserve the original provider error alongside the normalized public category. The raw value should be protected and retained according to operational policy, while the customer sees a stable error code. This combination gives engineers the evidence needed to improve normalization without forcing every developer to understand provider-specific terminology.
Closing reference note
The final API error contract should be treated as part of the developer product, not merely an internal exception mapping. Review error responses during API design, SDK development and support incidents. When a recurring customer problem appears, improve the code, documentation and example together so the same issue becomes less likely in future integrations.
Reference implementation reminder
Keep provider-specific diagnostics available to authorized support teams so a normalized error can still be investigated. This separation gives developers a clean API while preserving engineering evidence.
Release and maintenance note
When an API evolves, keep error handling backward compatible. Existing codes should retain their documented meaning, while additional diagnostics can be added as optional fields. This lets enterprise integrations upgrade without changing their core control flow.