Quick take
Support should not need to know every provider-specific code by heart. Normalize error codes into categories, show the safest user-facing response, and preserve the raw provider code for engineering escalation.
Error-code runbook
Group provider-specific errors into categories support can understand.
| Category | Support action | Engineering evidence |
|---|---|---|
| Temporary unavailable | Ask the user to retry after a short wait or use fallback. | Recipient, country, status timeline, provider code, carrier metadata. |
| Invalid or unreachable number | Ask the user to confirm phone number and country. | E.164 value, validation result, destination country, provider response. |
| Carrier or provider filtering | Avoid promising delivery; escalate with message evidence. | Template, sender identity, route, country, error code, raw payload. |
| Sender identity issue | Check launch readiness before retrying. | 10DLC/toll-free/sender ID status, template approval, use case, sender used. |
| Fraud or pumping control | Use safe copy and escalate only when the account action is legitimate. | Rule category, risk score, country, IP/device signals, attempt history. |
| Unknown | Collect evidence and avoid repeated blind retries. | All raw callbacks, message IDs, timestamps, provider logs, support notes. |
User-facing response pattern
Keep customer copy simple: say the code or alert could not be delivered yet, ask them to confirm the phone number, offer a retry window, and provide an alternate account recovery path where appropriate.
Internally, preserve exact error data. Externally, avoid exposing carrier, fraud, or provider internals that could confuse users or help attackers.
- What happened
- What the user can try
- When to retry
- When support will escalate
- What evidence support already has
Make failed messages easier to explain
Use Notilify to see SMS status, error category, sender, country, and retry history together.