Errors
Errors return the matching HTTP status and a JSON body with a stable error code and a human-readable message.
Errors return the matching HTTP status and a JSON body with a stable error
code and a human-readable message.
{
"error": "insufficient_balance",
"message": "Wallet balance 0.20 is below the price 0.65."
}Codes
| Status | Error | Meaning |
|---|---|---|
401 | unauthorized | Missing, revoked, or expired API key. |
400 | invalid_request | Malformed body or unknown service/country. |
402 | insufficient_balance | Your wallet can't cover the price. Top up and retry. |
402 | price_exceeded | The live price rose above your max_price. Re-check /v1/prices. |
404 | out_of_stock | No numbers available for that service + country right now. |
404 | not_found | Unknown activation id. |
429 | rate_limited | Rate limit or concurrency cap hit. See X-RateLimit-Reset. |
500 | server_error | Temporary server error — retry with backoff. |
Retrying
429 and 5xx are safe to retry with exponential backoff. Never retry a 4xx
other than 429 without changing the request — a failed buy charges nothing, so
you can safely re-create the activation.