# 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](https://hodlproxy.com/docs/username-parameters) |
| 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`](https://hodlproxy.com/docs/api#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 |

> Info: The gateway never answers `429`. There is no rate limit on your side; a `429` always comes from the target and means you should pace requests to that domain or spread them over more sessions.


## 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

1. Run the simplest request: `curl -x http://USER:PASS@res.hodlproxy.com:9000 https://api.ipify.org` with no parameters. If it works, the problem is in a parameter or in your client.
2. Check the proxy scheme: the proxy URL starts with `http://` (or `socks5h://` on 9001), never `https://`, even for HTTPS targets.
3. Add parameters back one at a time. `400` names the bad one; `502` on a narrow combination means nobody is online there right now.
4. Whitelist users: compare the address in **Settings → Whitelist** with the output of `curl https://api.ipify.org` **without** proxy, run on the same machine. Cloud instances often egress through a NAT gateway with a different address.
5. Check the balance of the network you are actually using: residential and mobile traffic are separate balances.
6. Look for environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`) that override what you pass in code.
7. 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](https://hodlproxy.com/docs/authentication#ip-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](https://hodlproxy.com/contact) explains how to reach the team; account holders open a ticket from the dashboard.


Source: https://hodlproxy.com/docs/errors