Error handling is where good integrations separate from fragile ones. Every error should lead to one of four actions: fix the request, retry later, wait for a condition to clear, or escalate to a human. If your code cannot say which, the error is being swallowed.
Read the status class first
The HTTP status class tells you who is responsible before you read any body.
- 2xx: the request worked. Still check the body status field, because an order can be accepted and later expire.
- 4xx: your request is wrong or not allowed. Retrying the same request will not help.
- 429: you are going too fast. Back off and honour any retry-after hint.
- 5xx: the server had a problem. Retry with backoff, within your deadline.
Common application errors and their meaning
Authentication and permission
A 401 means the key is missing, expired or malformed. A 403 means the key is valid but not allowed to do this. Neither is retryable. Alert the owner of the integration rather than looping.
Balance and pricing
An insufficient balance response should pause the flow and notify a person who can top up. Do not keep retrying orders, since each attempt is wasted traffic. A price changed or price too high response means your ceiling is below the current rate. Refresh the catalogue and decide whether to accept the new price.
Stock and availability
No numbers available is not a failure of your code. It is a business condition. Offer an alternative service, country or a wait-and-notify option instead of showing a generic error.
Validation
A 400 or 422 with field-level detail usually points to a malformed country code, an unknown service identifier or a badly formatted number. Log the field name and the value type, never the full phone number.
Design a stable internal error model
Do not leak upstream codes straight to your UI. Translate them into your own small set, such as retryable, user_fixable, capacity, auth and internal. Your front end then needs only five behaviours, and upstream changes stay behind a mapper.
{
"error": {
"type": "capacity",
"retryable": true,
"message": "No numbers right now",
"request_id": "req_8f21"
}
}Always keep the request id
Each response should carry an identifier. Store it with your own logs. When you contact support about a failed order, that id lets them find the exact upstream event in seconds instead of hours.
Handle errors by intent, not by string matching, and your workflow will stay calm when the API behaves badly.
Frequently asked questions
Should I show raw API errors to users?
No. Raw errors confuse people and can expose internal details. Map each upstream error to your own small set of types, then show a friendly message for each. Keep the original code and request id in your logs for support to use.
How do I treat unknown error codes?
Default to the safest behaviour: do not retry blindly, log the full response, alert the owner and show a generic but honest message. Then add the new code to your mapping once you understand what it means.
Do error codes change between versions?
They can. That is one reason to pin an API version and to match on error types and status classes instead of long message strings. Add contract tests that fail when a code you depend on changes shape.
How should I alert on errors without creating noise?
Alert on rates and patterns, not on single events. A handful of 5xx responses in an hour is normal, while a sustained rate above a threshold is not. Group alerts by error type, include the request id and a runbook link, and send authentication or balance problems straight to a named owner.
Keep going
Check the services list for current availability, then use the API docs to wire the flow into your own product. If you want background on the platform, visit the about page. Answers to everyday questions live in the help center, and the contact page reaches a person. More articles are on the blog. To place an order, log in to the verification dashboard.
Related reading: Rate Limiting and Backoff for SMS Verification APIs and Error Messages That Users Understand in OTP Flows.
