Errors
Every API error code and every gateway error code.
API errors
An error is a JSON body with a stable code:
{
"error": "insufficient_credit",
"message": "Not enough credit for this order.",
"request_id": "req_01J9ZK3V6T4M8Q2W7X5N0B1C3D",
"details": { "required_cents": 2500, "available_cents": 1200 }
}- Branch on
error, never onmessage. messageis written for people and safe to show to your users.request_idequals theX-Request-Idheader. Include it when you contact support.detailsis present only where listed below.
| Status | error | Meaning |
|---|---|---|
| 400 | validation_error | A parameter or body field is wrong or unknown. details names the field and the reason. |
| 400 | bad_target | The targeting is not valid for the network, for example a ZIP code on residential. |
| 401 | unauthorized | The API key is missing or not valid. |
| 401 | key_revoked | The API key was revoked. |
| 402 | insufficient_credit | Not enough credit for the order. details: required_cents, available_cents. |
| 403 | account_suspended | The account is suspended. Only GET /v1/me answers. |
| 403 | forbidden | The credential may not do this. |
| 404 | not_found | No such object on your account. |
| 409 | conflict | The object's state does not allow it, for example disabling the default proxy user. |
| 409 | username_taken | The proxy username is in use or was used before. |
| 409 | limit_reached | The account has its maximum of this object. details: limit, max. |
| 409 | idempotency_conflict | The Idempotency-Key was used with a different body. |
| 409 | idempotency_in_flight | The first request with this key is still running. Retry after Retry-After. |
| 422 | limit_below_usage | A proxy user's new limit is below what it already used. |
| 422 | product_unavailable | The product cannot be bought right now. |
| 422 | below_min, above_max | The amount is outside the product's min_gb and max_gb. |
| 422 | promo_invalid | The promo code is not valid. |
| 429 | rate_limited | Too many requests. Wait for Retry-After seconds. |
| 500 | internal_error | Something failed on our side. Retry; if it persists, send us the request_id. |
| 502 | upstream_error | The network could not complete the request. Retry shortly. |
| 503 | maintenance | The API is briefly unavailable. Retry shortly. |
POST /v1/checkout/quote does not use the 4xx codes for a cart that cannot be bought: it answers 200 with is_valid: false and the same code in invalid_reason.
Gateway errors
When the gateway refuses a proxy connection, an HTTP proxy client gets the status below with two headers: X-Proxy-Error with the code and X-Proxy-Request-Id. A SOCKS5 client gets the closest SOCKS reply (general failure, not allowed, or network unreachable) and the connection closes.
| Status | X-Proxy-Error | Meaning | What to do |
|---|---|---|---|
| 407 | auth_failed | Unknown proxy user, wrong password, or the user is disabled. | Check the username and password. |
| 400 | bad_target | The username's tokens are malformed or not supported by the network. | See Targeting. |
| 429 | quota_exhausted | The network's data balance is used up. | Buy data. |
| 429 | user_limit_exhausted | The proxy user reached its own limit for the network. | Raise the limit or use another proxy user. |
| 422 | quota_expired | The network's balance passed its valid_until date. | Buy data to extend it. |
| 429 | concurrency_limit | Too many connections open at once. | Close connections or lower your parallelism. |
| 403 | account_suspended | The account is suspended. | Check GET /v1/me for the reason. |
| 403 | target_blocked | The destination is blocked: mail ports and private addresses. | Use an allowed destination. |
| 503 | network_provisioning | The mobile network is still being set up after a purchase. | Retry in a moment. |
| 503 | no_node_for_target | No IP is available for the location. | Widen the target or retry later. |
| 502 | upstream_error | The connection through the network failed. | Retry; with a session, try a new session id. |