Error definitions

ISP errors are returned by the individual IP, not by a central gateway. The envelope is similar to the gateway products — HTTP status + helodata code + X-Helodata-Error-Code — but the set of possible codes is smaller because there's no username grammar to parse.

ISP error codes

Status	helodata code	X-Helodata-Error-Code	Meaning	What to do
401	20003	unknown-subuser	Sub-user doesn't exist	Check dashboard
403	—	kyc-required	Account flagged for a risk review; KYC pending	See KYC
403	—	batch-expired	Batch's billing period ended	See IP management → Renew
403	—	batch-grace-period	Batch is in 7-day grace; functional but warning you	Renew soon
403	—	ip-released	IP was released back to the pool	Remove from your client's list
403	—	restricted-category-*	Target is on the restricted list	See Restricted targets
403	—	account-suspended	Account suspended	Contact support
407	20003	auth-failed	Wrong password	Verify, then rotate if leaked
407	20003	not-whitelisted	Source IP not in this batch's whitelist	Add IP in dashboard
429	30002	concurrent-limit	Too many concurrent connections to this IP	Spread load across more IPs
429	30002	rps-limit	Too many requests per second to this IP	Add jitter, spread load
502	40001	upstream-tls-error	Target TLS handshake failed	See SSL errors
522	—	upstream-timeout	Target unreachable from this IP	Retry on a different IP from your batch
524	—	target-timeout	Target didn't respond in time	Retry or extend timeout

Health-aware retries

Because ISP IPs are stable, an IP that just returned 502/522/429 is likely to fail again on the next attempt. Always retry on a different IP from your batch — never on the same one:

def request_with_failover(url, pool):
    for attempt in range(5):
        line = pool.next_alive()
        try:
            r = call(url, line)
            if r.status_code in (200, 301, 302, 304, 404):
                return r
            if r.status_code in (502, 522, 524, 429):
                pool.mark_bad(line)                    # cool this IP down
                continue
            return r                                    # other 4xx/5xx — pass through
        except Exception:
            pool.mark_bad(line)
    raise RuntimeError(f"All 5 attempts failed for {url}")

Target-originated errors

Pass-through, same as the gateway products. You won't see helodata's X-Helodata-Exit-IP header because each IP is the exit — but the target's response headers reach you unchanged.

A target 403 or Cloudflare 1020 typically means that specific IP got reputation-flagged. Either:

• Mark it dead and request a replacement
• Wait out the cool-down (reputation often recovers in a few hours)

When to suspect helodata vs the target

Symptom	Likely cause
407 on every request	helodata — auth wrong
522 on a single IP, others work	helodata — that IP is degraded; mark dead
522 across many IPs simultaneously	helodata — incident in that region
Target 403 on a few IPs, others work	Target — IP reputation, replace
Target 403 on every IP in a country	Target — country block, switch country
429 from target — same IP, same target, repeatedly	Target — rate limit, spread load

Related

• Residential error definitions — full pass-through error semantics
• 407 troubleshooting
• IP management — how to replace bad IPs