Errors & retries
When something goes wrong, the proxy answers with a status code before your request reaches the target.
A code from us is not a code from the site you are scraping. A 403 or a CAPTCHA
page is a successful proxy request that the destination refused. Everything below
happens earlier than that.
Every code
Section titled “Every code”| Code | What happened | What to do |
|---|---|---|
400 | We cannot proxy that address | Send a hostname or public IP |
407 | We do not recognize your account | Check your balance, then your credentials |
451 | The domain is blocked, your targeting asked for a blocked location or network, or a Scale Rotating login asked for a premium domain | Contact support, or use a Premium login |
551 | No exit matched your targeting | Loosen your targeting |
556 | You are over your request-rate limit | Slow down |
504 552 | We tried several exits and all of them failed | Retry |
554 557 | Something failed on our side | Retry |
Codes above 550 are ours. They are not defined in any RFC.
Fix your request
Section titled “Fix your request”400 means the target is not something we proxy. Loopback addresses and
bracketed IPv6 literals are rejected. Send a hostname or a public IPv4 address.
551 means you described a set of exits that is currently empty. Loosen the
narrowest option and try again, in this order:
- ZIP code covers a few thousand households
- ASN cuts you to one carrier
- Device OS has no fallback
- City, then state
Asking for a country a product has no exits in returns 551 too.
Retrying the identical request returns 551 again. Change the targeting instead.
A request that used to work can start returning 551 without your code
changing. Exits join and leave constantly, and a narrow combination that had
coverage an hour ago may have none now.
Fix your account
Section titled “Fix your account”407 usually means an empty balance, not a wrong password. A balance that
reaches zero suspends the account, and a suspended account is no longer
recognized at the proxy. It fails exactly as though the credentials were wrong.
On a monthly Scale plan the same thing happens when
the package runs out or the plan ends.
Check in this order:
- Your balance. Usage & statistics or the Bandwidth API.
- Whether options landed on the username. Targeting appends to the
password.
USERNAME-country-US:PASSWORDis an unknown user. - Your source IP, if you use IP whitelisting. A changed egress address fails the same way.
- The password itself.
A sub-account is also suspended when the master account’s balance runs out. If every sub-account fails at once, check the master.
451 carries its reason in the response body, as plain text. The status line is
always 451 Unavailable For Legal Reasons. Over CONNECT many clients show only the
status, so use the check under
Reading the code over HTTPS. A 451 is never billed.
See Acceptable use.
A 451 with the header X-Rayobyte-Block-Reason: targeting means the request hit a
blocked location or network.
Usually a targeting option asked for a sanctioned country, an occupied region of Ukraine,
Washington, DC, or a sensitive network’s ASN. Rarely, the destination address is on a
blocked network. If that block affects a legitimate business purpose, contact support and
we’ll review your use case.
556 is sent about five seconds after the request. A client timeout under
five seconds turns it into a timeout and hides the cause.
Premium domains on a Scale login
Section titled “Premium domains on a Scale login”A Scale Rotating ISP or Scale Rotating DC login is refused on premium domains. The refused request doesn’t reach the site and isn’t billed, and your other requests keep running. Retrying returns the same result. To reach the site, use a Premium login.
| How you connected | What your client sees |
|---|---|
| HTTP and HTTPS | 451, with the header X-Rayobyte-Block-Reason: premium-domain and a message in the body |
HTTPS, when the server name in your TLS handshake is a premium domain and differs from the CONNECT host, the handshake has no server name, or the first thing sent is another kind of TLS record | The tunnel opens, then closes with no status code or message |
| SOCKS5 | Reply 0x05, for every target. Scale logins are HTTP and HTTPS only |
A few hosts that are not on the list get the same refusal on these logins, with the same header and message.
The header tells this 451 apart from a policy block. A blocked domain gets no header,
and blocked targeting gets X-Rayobyte-Block-Reason: targeting. A domain on both lists
gets the policy block, with no header.
A closed tunnel looks like the transient failure described under
Retry. If it repeats on the same host, compare the name your client sends in
TLS with the host you sent in CONNECT.
504, 552, 554 and 557 are transient. Retry with a backoff, two attempts
rather than ten in a loop.
We retry internally before returning any of them, so your retry sits on top of
ours. A 552 or 557 is not billed, and neither are the attempts we made before
returning it. See How traffic is counted.
If 504 or 552 persists against one target while other targets work, that
target is refusing our exits rather than the network failing. See
Choosing a product.
A failure after the tunnel opens has no status code. Your TLS handshake is
already in flight, and an HTTP status line cannot be written into an encrypted
stream. The connection closes instead, so your client reports ECONNRESET.
Retry it like a 552. Those bytes are not billed.
Reading the code over HTTPS
Section titled “Reading the code over HTTPS”Over CONNECT, curl reports the tunnel result rather than the proxy’s status.
%{http_code} prints 000 and the message is CONNECT tunnel failed. Use -v
to see the real code and any X-Rayobyte-* header:
curl -sv -x USERNAME:[email protected]:8000 https://checkip.amazonaws.com 2>&1 | grep -iE '^< (HTTP|x-rayobyte)'Plain HTTP on the same port returns the code normally.
Retrying in code
Section titled “Retrying in code”import time, requests
RETRY = {504, 552, 554, 557}TERMINAL = {400, 407, 451, 551, 556}
def fetch(url, proxies, attempts=3): for i in range(attempts): try: r = requests.get(url, proxies=proxies, timeout=60) except requests.exceptions.ConnectionError: time.sleep(2 ** i) # tunnel closed mid-request continue if r.status_code in TERMINAL: raise RuntimeError(f"{r.status_code} {r.reason}") if r.status_code in RETRY: time.sleep(2 ** i) continue return r raise RuntimeError("out of attempts")Set a client timeout of at least 60 seconds. We may try several exits before
answering, and a 556 alone takes five.
Retrying a terminal code returns the same code.
Over SOCKS5
Section titled “Over SOCKS5”SOCKS5 has five reply bytes, so several causes share one.
| Reply | Cause |
|---|---|
0x00 | Success |
0x01 | Credentials not recognized, or over the request-rate limit |
0x04 | Something failed on our side |
0x05 | Blocked domain, blocked targeting, no exit matched your targeting, or a login without SOCKS5 |
0x07 0x08 | Unsupported command or address type |
0x01 and 0x05 each cover two causes, and one of each pair is worth retrying
while the other is not. Reproduce an ambiguous SOCKS5 failure over HTTP on port
8000 to get a specific code.
Getting help
Section titled “Getting help”Contact support with the timestamp, the entry point you connected to, and the exact targeting options you sent. The destination URL alone is not enough to find a request.
Was this page helpful?
Thanks. That helps us fix it.