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

# Error definitions

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

## Gateway-originated errors (ipdunar layer)

| Status | ipdunar code | `X-IPdunar-Error-Code`  | Meaning                                                                                                     | What to do                                                                              |
| ------ | ------------ | ----------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `400`  | `20002`      | `bad-username`          | Username doesn't match the grammar                                                                          | Re-check [Username format](https://docs.ipdunar.com/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](https://docs.ipdunar.com/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](https://docs.ipdunar.com/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, ipdunar passes it through unchanged. The presence of these headers tells you the proxy succeeded; the issue is downstream:

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

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

## 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-IPdunar-Error-Code`, `X-IPdunar-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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
