# Error definitions

Mobile uses the same error envelope as residential — HTTP status + `X-Helodata-Error-Code`. The full table is documented in [Residential error definitions](/products/overview/error-definitions.md). The mobile-specific codes are listed below.

## Mobile-specific gateway codes

| Status | `X-Helodata-Error-Code` | Meaning                                                            | What to do                             |
| ------ | ----------------------- | ------------------------------------------------------------------ | -------------------------------------- |
| `403`  | `kyc-required`          | Account hasn't completed KYC                                       | See [KYC](/account-and-billing/kyc.md) |
| `400`  | `sesstime-out-of-range` | TTL > 60 (mobile cap)                                              | Reduce `sesstime`                      |
| `502`  | `carrier-blackout`      | Carrier-level outage on the requested ASN                          | Switch ASN or retry in 5 min           |
| `502`  | `pool-empty-mobile`     | No matching mobile IPs (typically state+city+ASN over-constrained) | Drop `city`, then `state`              |
| `522`  | `device-offline`        | Selected device went offline mid-request                           | Retry — gateway will pick a new device |

## More retries, with backoff

Mobile devices come and go. The transient-error rate is roughly 2–3× residential. A reasonable retry policy:

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

import time, random
def request_with_retry(fn):
    for attempt in range(MAX_RETRIES):
        r = fn()
        if r.status_code not in RETRYABLE_GATEWAY:
            return r
        time.sleep(2 ** attempt + random.random())   # exponential + jitter
    return r                                          # last response
```

## Target-originated errors

Pass-through, same as residential. Always check for the `X-Helodata-Exit-IP` header — if it's present alongside a `403` from the target, the target is rejecting the IP, not helodata.

## Carrier rate limiting

Mobile carriers throttle their own IPs. A `429` from the target without `X-Helodata-Error-Code` likely means the target hit your IP's carrier-imposed limit. Rotate ASN, increase session diversity, or slow down per-IP.

## Related

* [Residential error definitions](/products/overview/error-definitions.md) — full code table
* [407](/troubleshooting/407.md) — auth issues
* [522](/troubleshooting/522.md) — timeouts


---

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