OtpGet API Error Codes Explained: NO_NUMBERS and NO_BALANCE
Two sms activation api error codes cause more support tickets than any others: NO_NUMBERS and NO_BALANCE. Both look like failures to a user, but they mean very different things and need different fixes. This article explains each code, what triggers it and how to handle it in code so your integration stays reliable.
Direct answer: NO_NUMBERS means the provider has no available numbers for the requested country and service at that moment. NO_BALANCE means your OtpGet account balance is too low to place the order. Fix the first by retrying or switching country, and the second by topping up.
What Is the NO_NUMBERS Error?
NO_NUMBERS is a stock error. You asked for a number in a specific country for a specific service, and the supplier has none available right now. It is not a bug in your code and not a billing problem.
Common reasons include:
- High demand during peak hours.
- A popular service that many users are verifying at once.
- A country with limited supply.
- A temporary outage at the supplier level.
How to Handle NO_NUMBERS Correctly
- Retry after a short delay, but do not loop endlessly.
- Offer the user an alternative country or service.
- Show a clear message such as "This option is temporarily out of stock".
- Log the request so you can see which countries run out most often.
Never auto-charge the user for a failed order. If you already deducted a balance, refund it immediately.
What Is the NO_BALANCE Error?
NO_BALANCE is a funding error on your side. The API reached OtpGet but your account did not have enough balance to pay for the number. This is your problem to solve, not the customer's.
Signs of NO_BALANCE:
- Every order fails at once, across all countries.
- The error appears even for cheap services.
- It starts after a period of heavy sales.
How to Handle NO_BALANCE Correctly
- Top up your balance immediately in the dashboard.
- Set up an alert when balance drops below a threshold.
- Pause ordering in your bot or website until funds arrive.
- Tell affected users to retry in a few minutes.
If you take payments from customers, you must also refund or credit any order that failed because of your empty balance.
Other Errors You Should Map
| Error type | Likely cause | Best response |
|---|---|---|
| Invalid API key | Wrong or rotated key | Check environment variables |
| Bad service code | Unsupported service | Validate against the docs |
| Timeout | No SMS arrived | Cancel and refund |
Designing a Robust Error Layer
The best integrations treat error codes as first-class events. Write a small mapping file that turns each code into a user message, an internal action and a refund decision. That single file prevents most support chaos.
For example, NO_NUMBERS should trigger "offer alternative", NO_BALANCE should trigger "notify admin", and a timeout should trigger "cancel and refund". Once the map exists, your code becomes predictable and easy to test.
Testing Errors Before You Go Live
- Try a country with low stock to reproduce NO_NUMBERS safely.
- Use a test account with a tiny balance to see NO_BALANCE.
- Confirm your refunds fire automatically in both cases.
- Check the API documentation for any updates to error names.
Frequently Asked Questions
Does NO_NUMBERS mean my account is blocked?
No. It only means there is no stock for that exact country and service right now.
Will NO_BALANCE fix itself?
No. You must top up. Orders will keep failing until your balance is positive.
Should I retry NO_NUMBERS automatically?
One or two retries with a short delay are fine. Endless retries waste requests and annoy users.
Can NO_BALANCE happen mid-order?
It is checked at order time, so a drop in balance between orders can trigger it suddenly.
How do I avoid both errors?
Keep a balance buffer and show users multiple country options so stock gaps do not block them.
Conclusion
Understanding these two sms activation api error codes is the difference between a stable integration and a support nightmare. Track them, map them and act on them. Register on OtpGet and read the docs before you code.
Related reading: more API guides on the OtpGet blog.