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

HTTPCodeMeaning
400invalid_bodyThe body is not valid JSON, or body is not a string.
400invalid_urlurl is missing, not http(s), too long, or contains credentials.
400invalid_methodThe method is not supported.
400invalid_headersheaders is not an object, has more than 60 entries, or a name or value is not valid.
400body_too_largeThe body for the target is larger than 5 MB.
400invalid_sessionThe session name has other characters than letters, digits and _ . : -, or is longer than 64.
400invalid_optionssession and fresh_ip were sent together.
400invalid_timeouttimeout_ms is not a whole number of at least 1000.
401invalid_api_keyThe key is missing, mistyped or revoked.
402credits_exhaustedNo credits left in this period.
403account_suspendedThe account is suspended.
403email_not_verifiedThe account's e-mail address is not confirmed yet. Open the link we sent, or have it sent again in the dashboard.
403ip_not_allowedThe key is restricted to other IP addresses than the one you are calling from.
403target_not_allowedThe target is in a private network or is not available on this service.
404not_foundUnknown endpoint or unknown request id.
413body_too_largeThe whole call is larger than 8 MB.
429rate_limitedToo many requests per second for your plan.
429concurrency_limitedToo 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.

HTTPCodeMeaning
424timeoutThe target did not answer within the timeout.
424target_unreachableThe name does not resolve or no connection could be opened.
424connection_failedThe connection broke before a complete answer arrived.
424tls_errorThe TLS handshake with the target failed, for example an invalid certificate.
424too_many_redirectsMore than 5 redirects.
424request_failedAny other failure on the way to the target.

Something on our side

HTTPCodeMeaning
503busyAll modems are in use. Retry after retry_after_ms.
503rotation_failedA fresh IP could not be obtained in time.
503executor_unavailableThe modem pool is temporarily not reachable.
503maintenanceThe service is paused for maintenance.
500internal_errorAn 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.