Status codes
What the gateway answers when a request cannot be served, what each code means, and what to change.
These codes come from the rotating gateways used by residential and mobile proxies. When the gateway cannot complete a request, it answers with one of them instead of the target’s response; none is charged. Anything else is the target’s own status, passed through unchanged. ISP and datacenter proxies behave differently and never answer with an error status; see How errors look.
| Code | Meaning | What to do |
|---|---|---|
402 Payment Required: | The plan these credentials belong to has no traffic left. Residential and mobile are separate plans with separate balances. | Top up that plan from the dashboard or the User API; enable auto top-up to avoid it. |
406 Not Acceptable: | The username is malformed: a session id that is too long, a username that is too short, a missing targeting parameter, a country value that is too long, or a TTL that is not a number or is out of range. | Compare the username against Targeting. Session ids are short strings, country values are two letters, ttl is an integer from 1 to 1440. |
407 Proxy Authentication Required: | Wrong username or password. | Copy the credentials from the dashboard again. The username must start with a valid pool selector; the password is case-sensitive and must be URL-encoded if it contains reserved characters. |
410 Gone: | A problem with the peer serving the request. | Retry. With a sticky session, the next request with the same id is moved to a new IP. |
417 Expectation Failed: | The location is invalid: the country, region or city does not exist or is spelled differently from what the gateway expects. | Check the ISO code and the lowercase, no-space spelling of region and city, for example region-england, city-newyorkcity. |
421 Misdirected Request: | The location exists but has no IP available right now, which happens in sparsely populated regions when every node is offline. | Widen the target one step: city to region, region to country, or add a second country. |
423 Locked: | The target or port is restricted. | See Limits and restrictions. Verified accounts can request an unlock from the dashboard or support@datafuel.ai. |
500 Internal Server Error / 503 Service Unavailable: | A fault on Datafuel’s side. The on-call engineers are notified automatically. | Retry with backoff. If it persists, check status.datafuel.ai and contact support with the time and the gateway you used. |
Telling gateway errors from target errors
The gateway’s own responses carry the header X-Datafuel-Gateway: 1. A 403, 429 or 503 without that header came from the target site, which means the request went through and the site refused it; those responses count as traffic like any other.
Retry guidance
410,421,500,503: safe to retry; use exponential backoff starting at one second.406,407,417: fix the request first; retrying the same one gives the same answer.402,423: the account needs an action from you before any retry can succeed.