Error definitions

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

Gateway-originated errors (helodata layer)

Status	helodata code	X-Helodata-Error-Code	Meaning	What to do
400	20002	bad-username	Username doesn't match the grammar	Re-check Username format
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	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
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:

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.