Error reference — Docs

Ours vs. theirs

We pass target responses through unchanged. If a target returns 403, you see a 403. If we have something to say (auth, policy, capacity), we wrap it in our own status code with an X-Proxy-Reason header explaining why.

Quick rule of thumb

407, 451, 502, 503, 504 with an X-Proxy-Reason header are ours. Everything else is the target talking back.

Auth and access codes

407 means we couldn't authenticate the request. 451 means the request violated our Acceptable Use Policy — see /aup. Both are terminal — no retry will fix them.

Upstream / target codes

Most production pain is target-side: 403/429/5xx from anti-bot systems. The single most effective remedy on rotating products is a retry — the next exit IP clears the previous block more often than not.

Diagnostic headers

On every response we add three headers that cost nothing to inspect:

X-Proxy-Exit-Country — ISO-2 of the exit country we routed through (e.g. DE).
X-Proxy-Pool — residential, mobile, datacenter, or datacenter-static.
X-Proxy-Reason — only on 4xx/5xx that we generate. Plain-text single-line explanation.

Retry decision table

Code	Source	Meaning	Retry	Guidance
`200`	target	OK	don’t	Nothing to do — the request landed.
`302 / 301`	target	Redirect from the target	don’t	Follow it (most clients do automatically). Not a proxy issue.
`401`	target	Target says you aren’t authenticated	don’t	Your auth on the target site is missing/wrong — not a proxy problem.
`403`	target	Target blocked the request	maybe	Common when a target ASN-blocks. On rotating products, retry — the next exit IP often clears it. Persistent 403 means picking a stronger pool (residential / mobile).
`407`	proxy	Proxy authentication required	don’t	Your proxy credentials are missing or wrong. Re-check USER:PASS, especially for embedded special characters that need URL-encoding.
`429`	target	Target rate-limited the request	retry	Back off, then retry — ideally with a different exit (drop the sticky token if any). On rotating products this is straightforward.
`451`	proxy	Acceptable Use violation	don’t	We blocked a request because the destination violates our AUP (sanctions list, CSAM, etc). Order is suspended pending review.
`502`	proxy	Upstream pool error	retry	The pool couldn’t complete the connection. Retry; if it persists, check /status and email support with the timestamp.
`503`	proxy	Constraint can’t be honoured	maybe	Country/carrier targeting requested but no inventory available right now. Drop the constraint or wait a few seconds; check the X-Proxy-Reason header.
`504`	proxy	Upstream timeout	retry	The exit IP took too long to reach the target. Retry on rotating products; on static, swap the IP via support if the same one keeps timing out.
`522`	target	Cloudflare connection-timed-out	retry	Often transient on the target side. Retry once. If repeated for the same target, lower concurrency.
`Connection reset`	target	Target dropped the TCP connection	retry	Almost always target-side. On rotating products a retry usually picks a different exit and recovers.