2extract Developer Documentation

When you make a request through the 2extract.com proxy gateway, there are two potential sources of errors:

Our Gateway: Errors related to your account, authentication, or proxy configuration.
The Target Website: Errors returned by the website you are trying to scrape.

To help you instantly distinguish between these, our gateway adds a special HTTP header to any error it generates: X-2extract-Error: [A human-readable error description] Rule of thumb: If you see the X-2extract-Error header, the problem is related to your proxy setup. If you don’t, the problem is on the target website’s side.

Gateway Errors (4xx & 5xx Codes)

These are errors generated by our system. Always check the X-2extract-Error header for specific details.

400 Bad Request

This means there is a mistake in how you configured your request.

`X-2extract-Error` Message	Meaning & How to Fix
`Invalid username parameter: [param]`	You’ve used a parameter that doesn’t exist. Check the spelling in our documentation.
`Conflicting targeting parameters...`	You’ve combined mutually exclusive parameters, like `-country-us` and `-asn-123`. Choose one targeting method.
`Invalid value for parameter: [param]`	The value you provided is incorrect (e.g., `-country-usa` instead of `-country-us`). Check the format.
`Missing required parameter...`	You’ve used a parameter that depends on another one (e.g., `-state-ca` without `-country-us`). Add the required dependency.
`Ambiguous city name: [city]...`	The city you’re targeting exists in multiple states. Add a `-state-[code]` parameter to clarify.
`Invalid format for header: X-2extract-Geolocation`	The syntax of your geolocation header is incorrect. Check the `lat=...,lon=...,rad=...` format.

407 Proxy Authentication Required

This is the most common error and is always related to your access credentials or account status.

`X-2extract-Error` Message	Meaning & How to Fix
`User authentication failed`	Your proxy username or password is incorrect. Double-check your credentials.
`IP address not whitelisted...`	Your server’s IP is not in the “Authorized IPs” list for this proxy. Add it in your proxy settings.
`Zero balance. Service suspended.`	Your account balance has run out. Top up your balance to reactivate your proxies.
`Traffic limit reached for proxy...`	This specific proxy has hit the usage limit you configured. Increase the limit in the proxy’s settings.

502 Bad Gateway

This indicates a temporary problem with the specific residential IP that was assigned to your request.

`X-2extract-Error` Message	Meaning & How to Fix
`No available proxies for the requested target...`	We currently don’t have any available IPs that match your specific targeting criteria (e.g., a very small city). Try broadening your target.
`Session IP is offline`	The IP for your sticky session has gone offline. Simply retry your request with the same session ID to get a new IP (unless you are using `-const`).
`Proxy connection failed`	The selected IP couldn’t connect to the target. This is a temporary network issue. Retry your request.

504 Gateway Timeout

This means the connection took too long.

`X-2extract-Error` Message	Meaning & How to Fix
`Target connection timeout`	Our proxy could not establish a connection with the target website in a reasonable time. The target might be down or blocking requests. Check the target and retry.
`Proxy tunnel timeout`	There was a network issue between our gateway and the exit IP. Retry your request to get a different IP.

Target Website Errors

If you receive an error code without an X-2extract-Error header, it means our proxy successfully connected to the target, but the target itself rejected your request. Here are the most common ones you’ll encounter while scraping:

HTTP Status	Name	Why it Happens & How to Fix
403 Forbidden	Forbidden	The target website has identified your request as non-human and blocked your IP address. Action: Rotate your IP immediately.
429 Too Many Requests	Rate Limited	You are sending requests too quickly. Action: Slow down your scraper (increase delays) and rotate your IP.
500 Internal Server Error	Server Error	The target website’s server has an internal problem. Action: Retry the request after a short delay.
503 Service Unavailable	Service Unavailable	The target website is overloaded or down for maintenance. Action: Retry the request after a longer delay (e.g., 15-30 minutes).

Getting Started

Guides & Concepts

Proxy Products

Troubleshooting & Help

Legal

Release Notes

Error Handling & Response Codes

Gateway Errors (4xx & 5xx Codes)

400 Bad Request

407 Proxy Authentication Required

502 Bad Gateway

504 Gateway Timeout

Target Website Errors

​Gateway Errors (4xx & 5xx Codes)

​400 Bad Request

​407 Proxy Authentication Required

​502 Bad Gateway

​504 Gateway Timeout

​Target Website Errors

Gateway Errors (4xx & 5xx Codes)

400 Bad Request

407 Proxy Authentication Required

502 Bad Gateway

504 Gateway Timeout

Target Website Errors