Error definitions

Mobile uses the same error envelope as residential — HTTP status + helodata code + X-Helodata-Error-Code. The full table is documented in Residential error definitions. The mobile-specific codes are listed below.

Mobile-specific gateway codes

Status	helodata code	X-Helodata-Error-Code	Meaning	What to do
403	—	kyc-required	Account flagged for a risk review; KYC pending	See KYC
400	20002	sesstime-out-of-range	TTL > 60 (mobile cap)	Reduce sesstime
502	40001	carrier-blackout	Carrier-level outage on the requested ASN	Switch ASN or retry in 5 min
502	40001	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:

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 — full code table
• 407 — auth issues
• 522 — timeouts