Error codes hub

When something fails, three signals tell you what went wrong. Read them in this order:

1. HTTP status — the gross category (auth, rate-limit, upstream, target)
2. X-Helodata-Error-Code response header — the precise reason (only on gateway-originated errors)
3. X-Helodata-Request-Id — give this to support when you need help

A pasted log line is worth a thousand guesses.

Quick triage

Status	helodata code	Most likely cause	First check
400	20002	Username syntax	Username format
401 / 407	20003	Wrong creds / IP not whitelisted	407 Proxy Authentication Required
403	—	Restricted target or KYC missing	X-Helodata-Error-Code and Restricted targets
429	30002	Rate limit	Rate limits
502	40001	Pool exhausted, TLS issue	SSL / TLS errors, loosen username filter
522	—	Upstream timeout	522 Connection timed out
524	—	Target was slow	Slow target — retry, raise client timeout
Cloudflare 1020 page	—	Geo or fingerprint detected	CAPTCHAs, IP location mismatch

How to read a failing request

A real example response:

HTTP/1.1 407 Proxy Authentication Required
X-Helodata-Error-Code: not-whitelisted
X-Helodata-Request-Id: req_01HX2K3PQ4M5
Content-Type: application/json

{"code":"not-whitelisted","message":"Source IP 203.0.113.5 isn't on the whitelist for sub-user sub_01HX..."}

The three things to extract:

• Status 407 → auth class
• not-whitelisted → your source IP isn't on the sub-user's whitelist
• req_01HX2K3PQ4M5 → save it; if you need to ask us, we'll find this specific call

Common scenarios

What you observe	Likely cause	Page
First request always returns 407	Wrong username syntax or password	407
Random 522 on a tiny city filter	Pool too small	522
Some sites work, others give SSL errors	Target's TLS misconfig or your CA bundle	SSL/TLS errors
Lots of CAPTCHAs from one country	Fingerprint mismatch or pool burnt	CAPTCHAs
Exit-IP geolocates wrong	MaxMind lag	IP location mismatch
5–10 s response times	Mobile, or anti-bot delay	Slow speeds
Page just doesn't render	JS-heavy site or block	Website won't load

When you can't tell from the error

Log the trio status + X-Helodata-Error-Code + X-Helodata-Request-Id and email [e-mail]. We can pull the full request record from the Request-Id for up to 7 days after the call.

Per-product error tables

The exhaustive code tables live in each product's reference:

• Residential error definitions
• Mobile error definitions
• ISP error definitions