Skip to content

API & developers

Error codes

Every error code the API returns — its HTTP status, what it means, and what to do about it.

Last updated
Updated
Reading time
3 min read
On this page5
  1. Request problems
  2. Account and money
  3. Orders, rentals and inventory
  4. Problems on our side
  5. Privacy of not-found errors

Errors share one shape and carry a stable code you can switch on. The message is written for people and safe to show to your users, but its wording may change — don't parse it.

JSON
{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is too low for this purchase. Add funds and try again."
  }
}

Most errors carry details with more to go on — fields for a validation error, your balance and the price for insufficient_balance — and every response has an X-Request-Id header worth logging.

Request problems

Code HTTP Meaning What to do
invalid_request 400 A parameter is missing or malformed. details.fields names each one. Fix the request; the message names the problem.
unauthorized 401 The API key is missing, malformed or revoked. Send Authorization: Bearer pc_live_… with an active key from API keys.
not_found 404 No endpoint has that path. Check the URL against the API reference.
method_not_allowed 405 The path exists, but not with that HTTP method — for example GET on a cancel endpoint. Use a method listed in the Allow header.
payload_too_large 413 The JSON body is larger than 16 KB. Send only the documented fields.
service_not_found 404 No enabled service has that slug or id. Check GET /api/v1/services.
country_not_found 404 We don't sell numbers in that country. Check GET /api/v1/countries.
order_not_found 404 No order with that id on your account. Check the id.
rental_not_found 404 No rental with that id on your account. Check the id.

Account and money

Code HTTP Meaning What to do
insufficient_balance 402 Your balance doesn't cover the price. Nothing was charged. Add funds.
account_disabled 403 The API key is valid, but its account is disabled. Contact support.
not_available 403 That inventory isn't on sale to your account — during the beta, real carrier numbers, for orders and rentals alike. Wait for launch. See Beta status.
user_not_found 404 The account behind the key no longer exists. Contact support.

Adding funds happens in the dashboard, not through the API, so deposit and card-payment errors appear on the Billing page rather than here.

Orders, rentals and inventory

Code HTTP Meaning What to do
no_inventory 409 Nothing is in stock for that service and country right now. If an order had already been created, it was marked failed and refunded in full. Try another country, or again shortly.
price_above_max 409 Every in-stock offer costs more than your max_price. Nothing was charged. Raise max_price or choose another country.
invalid_state 409 The action doesn't fit the current status — for example, cancelling an order after an SMS arrived, or changing a rental that has ended. Fetch the order or rental and check its status.
idempotency_conflict 409 That Idempotency-Key was already used for a different request. Use a new key for a new purchase. See Idempotent orders.
rate_limited 429 Too many requests or purchases in a short time. Wait Retry-After seconds. See Rate limits.

Problems on our side

Code HTTP Meaning What to do
internal_error 500 Something failed on our side. Retry with the same Idempotency-Key. If it keeps happening, email support with the X-Request-Id.
provider_error 502 Our carrier returned an error. Retry shortly.

Privacy of not-found errors

You only ever see your own orders and rentals. An id that belongs to another account gets the same 404 as one that doesn't exist.