Errors
Errors are JSON with a stable code for your program and a message for you. No error is ever charged.
{
"error": {
"code": "target_unreachable",
"message": "The target could not be reached. This request was not charged.",
"charged": false
},
"request_id": "req-n"
}request_id is also sent as the X-Request-Id response header. Some errors add retry_after_ms.
Your request was not accepted
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_body | The body is not valid JSON, or body is not a string. |
| 400 | invalid_url | url is missing, not http(s), too long, or contains credentials. |
| 400 | invalid_method | The method is not supported. |
| 400 | invalid_headers | headers is not an object, has more than 60 entries, or a name or value is not valid. |
| 400 | body_too_large | The body for the target is larger than 5 MB. |
| 400 | invalid_session | The session name has other characters than letters, digits and _ . : -, or is longer than 64. |
| 400 | invalid_options | session and fresh_ip were sent together. |
| 400 | invalid_timeout | timeout_ms is not a whole number of at least 1000. |
| 401 | invalid_api_key | The key is missing, mistyped or revoked. |
| 402 | credits_exhausted | No credits left in this period. |
| 403 | account_suspended | The account is suspended. |
| 403 | email_not_verified | The account's e-mail address is not confirmed yet. Open the link we sent, or have it sent again in the dashboard. |
| 403 | ip_not_allowed | The key is restricted to other IP addresses than the one you are calling from. |
| 403 | target_not_allowed | The target is in a private network or is not available on this service. |
| 404 | not_found | Unknown endpoint or unknown request id. |
| 413 | body_too_large | The whole call is larger than 8 MB. |
| 429 | rate_limited | Too many requests per second for your plan. |
| 429 | concurrency_limited | Too many requests at the same time for your plan. |
The target did not answer
These use HTTP 424: your call was fine, but the request to the target failed.
| HTTP | Code | Meaning |
|---|---|---|
| 424 | timeout | The target did not answer within the timeout. |
| 424 | target_unreachable | The name does not resolve or no connection could be opened. |
| 424 | connection_failed | The connection broke before a complete answer arrived. |
| 424 | tls_error | The TLS handshake with the target failed, for example an invalid certificate. |
| 424 | too_many_redirects | More than 5 redirects. |
| 424 | request_failed | Any other failure on the way to the target. |
Something on our side
| HTTP | Code | Meaning |
|---|---|---|
| 503 | busy | All modems are in use. Retry after retry_after_ms. |
| 503 | rotation_failed | A fresh IP could not be obtained in time. |
| 503 | executor_unavailable | The modem pool is temporarily not reachable. |
| 503 | maintenance | The service is paused for maintenance. |
| 500 | internal_error | An unexpected error. Send us the request_id. |
We never answer 502 or 504. If you see one, it came from the network between you and us, and the body will not be JSON.