# Error codes hub

When something fails, three signals tell you what went wrong. Read them in this order:

1. **HTTP status** — the gross category (auth, rate-limit, upstream, target)
2. **`X-Helodata-Error-Code`** response header — the precise reason (only on gateway-originated errors)
3. **`X-Helodata-Request-Id`** — give this to support when you need help

A pasted log line is worth a thousand guesses.

## Quick triage

| Status                 | Most likely cause                | First check                                                                                                |
| ---------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `400`                  | Username syntax                  | [Username format](/getting-started/username-format.md)                                                     |
| `401` / `407`          | Wrong creds / IP not whitelisted | [407 Proxy Authentication Required](/troubleshooting/407.md)                                               |
| `403`                  | Restricted target or KYC missing | `X-Helodata-Error-Code` and [Restricted targets](/products/overview/restricted-targets.md)                 |
| `429`                  | Rate limit                       | [Rate limits](/api-reference/rate-limits.md)                                                               |
| `502`                  | Pool exhausted, TLS issue        | [SSL / TLS errors](/troubleshooting/ssl-errors.md), loosen username filter                                 |
| `522`                  | Upstream timeout                 | [522 Connection timed out](/troubleshooting/522.md)                                                        |
| `524`                  | Target was slow                  | Slow target — retry, raise client timeout                                                                  |
| Cloudflare `1020` page | Geo or fingerprint detected      | [CAPTCHAs](/troubleshooting/captchas.md), [IP location mismatch](/troubleshooting/ip-location-mismatch.md) |

## How to read a failing request

A real example response:

```
HTTP/1.1 407 Proxy Authentication Required
X-Helodata-Error-Code: not-whitelisted
X-Helodata-Request-Id: req_01HX2K3PQ4M5
Content-Type: application/json

{"code":"not-whitelisted","message":"Source IP 203.0.113.5 isn't on the whitelist for sub-user sub_01HX..."}
```

The three things to extract:

* **Status 407** → auth class
* **`not-whitelisted`** → your source IP isn't on the sub-user's whitelist
* **`req_01HX2K3PQ4M5`** → save it; if you need to ask us, we'll find this specific call

## Common scenarios

| What you observe                        | Likely cause                             | Page                                                             |
| --------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------- |
| First request always returns 407        | Wrong username syntax or password        | [407](/troubleshooting/407.md)                                   |
| Random `522` on a tiny city filter      | Pool too small                           | [522](/troubleshooting/522.md)                                   |
| Some sites work, others give SSL errors | Target's TLS misconfig or your CA bundle | [SSL/TLS errors](/troubleshooting/ssl-errors.md)                 |
| Lots of CAPTCHAs from one country       | Fingerprint mismatch or pool burnt       | [CAPTCHAs](/troubleshooting/captchas.md)                         |
| `Exit-IP` geolocates wrong              | MaxMind lag                              | [IP location mismatch](/troubleshooting/ip-location-mismatch.md) |
| 5–10 s response times                   | Mobile, or anti-bot delay                | [Slow speeds](/troubleshooting/slow-speeds.md)                   |
| Page just doesn't render                | JS-heavy site or block                   | [Website won't load](/troubleshooting/website-wont-load.md)      |

## When you can't tell from the error

Log the trio `status + X-Helodata-Error-Code + X-Helodata-Request-Id` and email <support@helodata.com>. We can pull the full request record from the `Request-Id` for up to 7 days after the call.

## Per-product error tables

The exhaustive code tables live in each product's reference:

* [Residential error definitions](/products/overview/error-definitions.md)
* [Mobile error definitions](/products/overview-1/error-definitions.md)
* [ISP error definitions](/products/overview-2/error-definitions.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/troubleshooting/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.