Errors & limits
Handle API errors, pending results and uncertain requests.
Check the response table for the method you called: the same HTTP code can mean different things in different methods. When reporting a problem, include statusCode, error.type and error.description so you can identify the cause.
Pending is not terminal failure
On Receive SMS, 202 / SMS_NOT_YET_RECEIVED intentionally uses the error object for waiting. Handle it first, wait, and poll within the saved order lifetime. Do not classify every error object as a terminal failure.
Limits and transport failures
Handle limit errors documented for the selected method, including ACCESS_LIMITED where present. Each method has its own documented limit responses. A client timeout, connection failure, or non-JSON response is distinct from a documented API error. There are no automatic retries in the endpoint examples. For number requests with an uncertain result, inspect current orders before repeating them.
Response index
A dash means the source documents the HTTP description without a structured error-type example. Error types and descriptions below are retained from the source, including differences between methods.
| HTTP | error.type | Description | Methods |
|---|---|---|---|
| 400 | APIKEY_NOT_SET | The apikey header is missing, empty or invalid in length. | Get balance, User information |
| 400 | APIKEY_NOT_SET | No ApiKey found | Operators, Conversion rates, Country operator prices |
| 400 | APIKEY_NOT_SET | The apikey header is missing, empty or shorter than 30 characters. | Message type settings |
| 401 | USER_NOT_FOUND | No user was found for the supplied API key. | Message type settings |
| 402 | RATELIMIT_EXCEED | The request rate limit was exceeded. This API uses HTTP 402 for this error. | Message type settings |
| 403 | USER_BANNED | The user is banned. | Message type settings |
| 500 | SERVER_ERROR | Internal server error. The description may contain a specific exception message when error details are enabled. | Message type settings |
| 402 | RATELIMIT_EXCEED | API rate limit exceeded. | All number counts |
| 405 | INVALID_PARAMS | Invalid country or service parameter. | Service price |
| 405 | INVALID_PARAMS | Invalid parameters | Service prices by country, Get number, Get number by operator, Receive SMS, Clear SMS, Stop SMS, Cancel order |
| 407 | LOW_BALANCE | Your balance is too low to receive sms for selected country and service. | Get number |
| 411 | ACCESS_LIMITED | API access limited by low karma or ratelimits | Get number, Receive SMS, Stop SMS, Cancel order, Block number |
| 500 | NUMBER_FETCH_FAIL | Failed to fetch number | Get number |
| 501 | PRICE_FETCH_FAIL | Number not found | Get number |
| 502 | NUMBER_NOT_FOUND | Number not found. | Get number |
| 503 | SERVER_BUSY | Server overload, try later. | Get number |
| 407 | — | Your balance is too low to receive sms for selected country and service. | Get number by operator |
| 411 | — | API access limited by low karma or ratelimits | Get number by operator |
| 500 | — | Failed to fetch number | Get number by operator |
| 501 | — | Number not found | Get number by operator |
| 502 | — | Number not found. | Get number by operator, Number status |
| 503 | — | Server overload, try later. | Get number by operator |
| 406 | INVALID_ORDER_FORMAT | Order ID format is invalid or not found | Receive SMS |
| 407 | LOW_BALANCE | We received SMS but your balance is not enough to pay it. | Receive SMS |
| 410 | ORDER_CLOSED | This order is closed and unavailable | Receive SMS |
| 500 | SMS_FETCH_FAIL | Failed to fetch SMS. | Receive SMS |
| 501 | SERVER_FAIL | Server failed to process request. | Receive SMS, Current orders, Clear SMS, Stop SMS, Block number |
| 503 | SERVER_BUSY | The server is overloaded and experiencing performance issues. Please try later. | Receive SMS, Current orders, Stop SMS, Cancel order, Block number |
| 405 | INVALID_NUMBER_FORMAT | Invalid number format | Number status |
| 406 | ORDER_NOT_FOUND | Order ID format is invalid or not found | Number status, Stop SMS, Cancel order, Block number |
| 500 | SERVER_ERROR | Internal server error. The description may include diagnostic details. | Number status |
| 501 | — | Server failed to process request. | Number status |
| 503 | — | The server is overloaded and experiencing performance issues. Please try later. | Number status |
| 504 | — | av2.resp.504.desc — the source does not provide a resolved description for this response. | Number status |
| 404 | NO_SMS_TO_CLEAN | No SMS received, or there's unpaid SMS waiting. | Clear SMS |
| 406 | ORDER_NOT_FOUND | Order not found. | Clear SMS |
| 503 | SERVER_BUSY | No SMS received, or there's unpaid SMS waiting. | Clear SMS |
| 501 | SERVER_BUSY | Server failed to process request. | Cancel order |
| 405 | INVALID_PARAMS | Invalid number format | Block number |