# Error definitions

ISP errors are returned by the individual IP, not by a central gateway. The envelope is similar to the gateway products — HTTP status + `X-Helodata-Error-Code` — but the set of possible codes is smaller because there's no username grammar to parse.

## ISP error codes

| Status | `X-Helodata-Error-Code` | Meaning                                             | What to do                                                                       |
| ------ | ----------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------- |
| `401`  | `unknown-subuser`       | Sub-user doesn't exist                              | Check dashboard                                                                  |
| `403`  | `kyc-required`          | Account hasn't completed KYC                        | See [KYC](/account-and-billing/kyc.md)                                           |
| `403`  | `batch-expired`         | Batch's billing period ended                        | See [IP management → Renew](/products/overview-2/ip-management.md#extend--renew) |
| `403`  | `batch-grace-period`    | Batch is in 7-day grace; functional but warning you | Renew soon                                                                       |
| `403`  | `ip-released`           | IP was released back to the pool                    | Remove from your client's list                                                   |
| `403`  | `restricted-category-*` | Target is on the restricted list                    | See [Restricted targets](/products/overview/restricted-targets.md)               |
| `403`  | `account-suspended`     | Account suspended                                   | Contact support                                                                  |
| `407`  | `auth-failed`           | Wrong password                                      | Verify, then rotate if leaked                                                    |
| `407`  | `not-whitelisted`       | Source IP not in this batch's whitelist             | Add IP in dashboard                                                              |
| `429`  | `concurrent-limit`      | Too many concurrent connections to this IP          | Spread load across more IPs                                                      |
| `429`  | `rps-limit`             | Too many requests per second to this IP             | Add jitter, spread load                                                          |
| `502`  | `upstream-tls-error`    | Target TLS handshake failed                         | See [SSL errors](/troubleshooting/ssl-errors.md)                                 |
| `522`  | `upstream-timeout`      | Target unreachable from this IP                     | Retry on a different IP from your batch                                          |
| `524`  | `target-timeout`        | Target didn't respond in time                       | Retry or extend timeout                                                          |

## Health-aware retries

Because ISP IPs are stable, an IP that just returned `502`/`522`/`429` is likely to fail again on the next attempt. Always **retry on a different IP** from your batch — never on the same one:

```python
def request_with_failover(url, pool):
    for attempt in range(5):
        line = pool.next_alive()
        try:
            r = call(url, line)
            if r.status_code in (200, 301, 302, 304, 404):
                return r
            if r.status_code in (502, 522, 524, 429):
                pool.mark_bad(line)                    # cool this IP down
                continue
            return r                                    # other 4xx/5xx — pass through
        except Exception:
            pool.mark_bad(line)
    raise RuntimeError(f"All 5 attempts failed for {url}")
```

## Target-originated errors

Pass-through, same as the gateway products. You won't see helodata's `X-Helodata-Exit-IP` header because each IP **is** the exit — but the target's response headers reach you unchanged.

A target `403` or Cloudflare `1020` typically means **that specific IP** got reputation-flagged. Either:

* Mark it dead and request a [replacement](/products/overview-2/ip-management.md#replace-a-dead-ip)
* Wait out the cool-down (reputation often recovers in a few hours)

## When to suspect helodata vs the target

| Symptom                                              | Likely cause                              |
| ---------------------------------------------------- | ----------------------------------------- |
| `407` on every request                               | helodata — auth wrong                     |
| `522` on a single IP, others work                    | helodata — that IP is degraded; mark dead |
| `522` across many IPs simultaneously                 | helodata — incident in that region        |
| Target `403` on a few IPs, others work               | Target — IP reputation, replace           |
| Target `403` on every IP in a country                | Target — country block, switch country    |
| `429` from target — same IP, same target, repeatedly | Target — rate limit, spread load          |

## Related

* [Residential error definitions](/products/overview/error-definitions.md) — full pass-through error semantics
* [407 troubleshooting](/troubleshooting/407.md)
* [IP management](/products/overview-2/ip-management.md) — how to replace bad IPs


---

# 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-2/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.