# Error definitions

The gateway returns errors with both the standard HTTP status code and a `X-Helodata-Error-Code` header that pinpoints the exact cause. Pair the status with the header before retrying.

## Gateway-originated errors (helodata layer)

| Status | `X-Helodata-Error-Code` | Meaning                                                                             | What to do                                                      |
| ------ | ----------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `400`  | `bad-username`          | Username doesn't match the grammar                                                  | Re-check [Username format](/getting-started/username-format.md) |
| `400`  | `unknown-region`        | Region code not recognized                                                          | Use ISO-3166 alpha-2                                            |
| `400`  | `state-without-region`  | `state` segment without `region`                                                    | Add `region`                                                    |
| `400`  | `city-without-state`    | `city` segment without `state`                                                      | Add `state`                                                     |
| `400`  | `session-incomplete`    | `session` without `sesstime` (or vice versa)                                        | Always pair them                                                |
| `400`  | `sesstime-out-of-range` | TTL > 30 (residential)                                                              | Reduce `sesstime`                                               |
| `401`  | `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`  | `auth-failed`           | Bad password                                                                        | Verify, then rotate if leaked                                   |
| `407`  | `not-whitelisted`       | Source IP not in whitelist                                                          | Add IP in dashboard                                             |
| `429`  | `concurrent-limit`      | Too many concurrent connections                                                     | Throttle client or upgrade plan                                 |
| `429`  | `rps-limit`             | Too many requests per second                                                        | Backoff and retry with jitter                                   |
| `502`  | `pool-empty`            | No matching IPs in pool                                                             | Loosen geo/ASN filter                                           |
| `502`  | `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: 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/products/overview/error-definitions.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.