Errors & Troubleshooting

Every HTTP code the gateway can return, what it means, and how to fix it.

HTTP status codes

Code	Name	Meaning	Fix
402	Payment Required	Escrow balance is below the request price (SPACE).	Run spacerouter escrow deposit.
407	Proxy Authentication Required	Payment headers landed on the inner request instead of the CONNECT, or the challenge signature was rejected.	Use the SDK helper — it puts headers on CONNECT and signs each fresh challenge.
429	Too Many Requests	You're hitting the rate limit (60 RPM per wallet by default).	Honor the Retry-After header and back off.
502	Bad Gateway / Upstream Error	The Provider reached your target site but got an error from it (e.g. site rejected the IP).	Try a different region or IP type.
503	Service Unavailable	No Provider currently matches your region/IP-type filter.	Drop the type filter or pick a more popular region.

Common scenarios

"It worked yesterday, today every request is 402"

Almost always: your escrow balance has run out. Check it with spacerouter escrow balance 0xYourAddress, then top up with spacerouter escrow deposit <amount_wei>.

If the balance is fine but the gateway still returns 402 api_key_auth_deprecated, your client is on the legacy Proxy-Authorization: Basic sr_live_… flow. Upgrade to the v1.5 SDK and switch to the wallet + payment constructor.

Some target sites block me

The IP type matters. Hosting IPs are commonly blocked by anti-bot systems. Try type=residential or type=mobile.

"503 No nodes available" for every request

Your region/type combination has no live Providers right now. Pick a more popular region (e.g. US, KR, JP) or drop the type filter and let the gateway pick.

SPACE deposit transaction reverts

Most likely: your wallet has SPACE but no CTC for gas, or the escrow allowance was never granted. The CLI handles approval automatically; if you're calling the contract directly, run token.approve(escrow, amount) first.

SDK calls hang forever

You're behind a corporate firewall that blocks port 8080. Use the HTTPS gateway URL (https://gateway.spacerouter.org) — it tunnels over 443.

Get help

If you've checked the above and you're still stuck:

• Email [email protected] with the request ID from the response headers (X-Request-Id).

• For SDK bugs, file an issue on the public repos.