Integrate · Errors & troubleshooting
Every status the gateway can answer with, and what to change.
Gateway errors come with a short reason in the body. Target errors pass through untouched. Telling the two apart is most of troubleshooting.
Responses from the gateway#
| Status | Reason in the body | Cause | Fix |
|---|---|---|---|
| 407 Proxy Authentication Required | invalid_credentials | Wrong username or password, or the connecting IP is not whitelisted and no credentials were sent | Copy the pair from the dashboard again; check the whitelist against curl https://api.ipify.org run without a proxy |
| 400 Bad Request | invalid_parameter: … | A username parameter is unknown or malformed, or the combination is invalid (-state- outside the US, -city- without -cc-) | Fix the string named in the body; see Targeting & sessions |
| 402 Payment Required | insufficient_balance | No traffic left on the pool network you are using, or the sub-user reached its limit | Buy traffic or raise the sub-user limit; check GET /v1/balance |
| 403 Forbidden | blocked_destination | The destination or port is not allowed (port 25, or a target on our deny list), or the account is suspended | Read the reason; contact us if you believe a destination is wrongly listed |
| 502 Bad Gateway | no_exit_available / exit_failed | No device online for the parameters, or the chosen device dropped mid-request | Retry once (rotation already picks another exit); broaden the targeting if it repeats |
| 504 Gateway Timeout | target_timeout | The target did not answer through the exit within the time limit | Retry with a new IP; raise your client timeout if the target is slow by nature |
Gateway error or target error?#
A gateway error arrives before any byte from the target: on an HTTPS request it is the response to the CONNECT, which most clients surface as a connection or proxy error rather than an HTTP response. A target error arrives inside the tunnel with the target's own headers and body. curl -v shows the difference immediately: look at which response follows CONNECT.
Diagnostic checklist#
- Run the simplest request:
curl -x http://USER:[email protected]:9000 https://api.ipify.orgwith no parameters. If it works, the problem is in a parameter or in your client. - Check the proxy scheme: the proxy URL starts with
http://(orsocks5h://on 9001), neverhttps://, even for HTTPS targets. - Add parameters back one at a time.
400names the bad one;502on a narrow combination means nobody is online there right now. - Whitelist users: compare the address in Settings → Whitelist with the output of
curl https://api.ipify.orgwithout proxy, run on the same machine. Cloud instances often egress through a NAT gateway with a different address. - Check the balance of the network you are actually using: residential and mobile traffic are separate balances.
- Look for environment variables (
HTTP_PROXY,HTTPS_PROXY,ALL_PROXY,NO_PROXY) that override what you pass in code. - If the TLS certificate fails to verify, something between you and the gateway intercepts TLS (corporate proxy, antivirus). The gateway never touches certificates.
Symptoms and their usual cause#
| You see | Usually means | Do this |
|---|---|---|
curl: (56) Received HTTP code 407 from proxy after CONNECT | Credentials rejected | Re-copy them; percent-encode special characters if you set your own password |
| The same IP on every request | Your client reuses one keep-alive connection, or you left a -sid- in the username | Close connections between requests or drop the session id |
A different IP on every request although -sid- is set | The lifetime is shorter than the gap between requests, or the id changes per request (a random value in a template) | Fix the id, raise -ttl- |
Connection reset by peer mid-download | The household went offline | Retry; with rotation it already uses another exit; on a sticky session the next request gets a new IP |
| Works in curl, fails in the browser | The browser has no proxy password or the flag ignores credentials | Use Playwright or Puppeteer authentication, or the whitelist |
| Target answers 403 or a CAPTCHA | The target scores the visit, not the proxy | Move to residential or mobile, add a sticky session for multi-step flows, match headers to the exit country, pace per domain |
| Everything is slow | Distant exit or a household on a weak line | Choose the country closest to the target, keep sessions short so the next one lands on a better line, or use datacenter or ISP for raw speed |
SSL certificate problem | TLS interception on your side | Remove the interception or trust its root; the gateway is not involved |
Still stuck#
Send us the exact request (credentials removed), the timestamp in UTC, the status and body you received and the exit IP if the request went through. The contact page explains how to reach the team; account holders open a ticket from the dashboard.