SMS API
Errors and retries
Understand SMS API errors and build reliable retry handling.
The SMS API returns structured errors when a request cannot be accepted.
Authentication error
{
"statusCode": 401,
"error": "ProviderAuthenticationError",
"code": "SMS_PROVIDER_AUTHENTICATION_FAILED",
"message": "The messaging account credentials were rejected by the provider.",
"providerCode": 1006
}Check the API key and partner ID. Do not retry unchanged credentials indefinitely.
Common provider codes
| Code | Meaning | Action |
|---|---|---|
200 | Successful request | Continue processing |
1001 | Invalid sender ID | Use an approved sender ID |
1002 | Network not allowed | Check destination/network permissions |
1003 | Invalid mobile number | Validate the recipient number |
1004 | Insufficient credits | Recharge before retrying |
1005 | Provider system error | Retry with backoff |
1006 | Invalid credentials | Correct credentials before retrying |
1008 | No delivery report | Try again later or reconcile asynchronously |
4090 | Internal provider error | Retry after five minutes |
4091 | Partner ID missing | Supply a valid partner ID |
4092 | API key missing | Supply a valid API key |
4093 | Account details not found | Verify the account configuration |
Retry policy
- Retry transient
502,503, and provider system errors with exponential backoff. - Do not automatically retry
401, invalid number, invalid sender, or insufficient-credit errors. - Use an application idempotency key or client reference to reconcile retries.
- For bulk requests, retry only failed items rather than the entire batch.
Never log API keys, message contents containing sensitive information, or full provider payloads in production logs.