> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/products/overview/error-definitions.md).

# Error definitions

The gateway returns errors with the HTTP status code, a numeric **helodata code**, and a `X-Helodata-Error-Code` header that pinpoints the exact cause. Pair them before retrying.

## Gateway-originated errors (helodata layer)

| Status | helodata code | `X-Helodata-Error-Code` | Meaning                                                                             | What to do                                                      |
| ------ | ------------- | ----------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `400`  | `20002`       | `bad-username`          | Username doesn't match the grammar                                                  | Re-check [Username format](/getting-started/username-format.md) |
| `400`  | `20002`       | `unknown-region`        | Region code not recognized                                                          | Use ISO-3166 alpha-2                                            |
| `400`  | `20002`       | `state-without-region`  | `state` segment without `region`                                                    | Add `region`                                                    |
| `400`  | `20002`       | `city-without-state`    | `city` segment without `state`                                                      | Add `state`                                                     |
| `400`  | `20002`       | `session-incomplete`    | `session` without `sesstime` (or vice versa)                                        | Always pair them                                                |
| `400`  | `20002`       | `sesstime-out-of-range` | TTL > 30 (residential)                                                              | Reduce `sesstime`                                               |
| `401`  | `20003`       | `unknown-subuser`       | Sub-user doesn't exist                                                              | Check dashboard                                                 |
| `403`  | —             | `restricted-category-*` | Target blocked — see [Restricted targets](/products/overview/restricted-targets.md) | Request exception                                               |
| `403`  | —             | `account-suspended`     | Account suspended for billing or abuse                                              | Contact support                                                 |
| `407`  | `20003`       | `auth-failed`           | Bad password                                                                        | Verify, then rotate if leaked                                   |
| `407`  | `20003`       | `not-whitelisted`       | Source IP not in whitelist                                                          | Add IP in dashboard                                             |
| `429`  | `30002`       | `concurrent-limit`      | Too many concurrent connections                                                     | Throttle client or upgrade plan                                 |
| `429`  | `30002`       | `rps-limit`             | Too many requests per second                                                        | Backoff and retry with jitter                                   |
| `502`  | `40001`       | `pool-empty`            | No matching IPs in pool                                                             | Loosen geo/ASN filter                                           |
| `502`  | `40001`       | `upstream-tls-error`    | Target TLS handshake failed                                                         | See [SSL errors](/troubleshooting/ssl-errors.md)                |
| `522`  | —             | `upstream-timeout`      | Backend IP unreachable                                                              | Retry — usually transient                                       |
| `522`  | —             | `insufficient-pool`     | Combined filter has <10 IPs                                                         | Loosen filter                                                   |
| `524`  | —             | `target-timeout`        | Target site didn't respond in time                                                  | Retry or extend client timeout                                  |

## Target-originated errors (pass-through)

When the target site responds with an error, helodata passes it through unchanged. The presence of these headers tells you the proxy succeeded; the issue is downstream:

```
X-Helodata-Exit-IP: 198.51.100.42
X-Helodata-Exit-Geo: us/ca/la
X-Helodata-Exit-ASN: 7922
```

If you see those headers alongside e.g. a `403` from the target, the target itself is rejecting the IP — not helodata.

## Common pass-through statuses to expect

| Status                 | Common cause                     | Mitigation                                      |
| ---------------------- | -------------------------------- | ----------------------------------------------- |
| `403` from target      | Anti-bot system rejected this IP | Rotate IP, add headers, slow down               |
| `429` from target      | Rate-limited by target           | Slow down per-IP, increase rotation             |
| `503` from target      | Target overloaded                | Retry with backoff                              |
| Cloudflare `1020` page | Geo or fingerprint failed        | Add headers, use sticky session, switch country |

## Retry strategy

Build retries from this table — different codes need different responses:

```python
RETRYABLE_GATEWAY = {429, 502, 522, 524}

def should_retry(status, err_code):
    if status in (400, 401, 403, 407):
        return False                          # config issue, no point retrying
    if status in RETRYABLE_GATEWAY:
        return True
    return False
```

For 429s with `rps-limit`, jitter for 1–5 seconds. For `pool-empty`, retry only after broadening the username filter.

## Logging recommendation

Log the trio `status`, `X-Helodata-Error-Code`, `X-Helodata-Exit-IP` on every request. It's enough to answer most "what went wrong" questions without re-running the call.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.helodata.com/products/overview/error-definitions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.