Skip to main content
When you make a request through the 2extract.com proxy gateway, there are two potential sources of errors:
  1. Our Gateway: Errors related to your account, authentication, or proxy configuration.
  2. 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 MessageMeaning & 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-GeolocationThe 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 MessageMeaning & How to Fix
User authentication failedYour 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 MessageMeaning & 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 offlineThe 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 failedThe 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 MessageMeaning & How to Fix
Target connection timeoutOur 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 timeoutThere 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 StatusNameWhy it Happens & How to Fix
403 ForbiddenForbiddenThe target website has identified your request as non-human and blocked your IP address. Action: Rotate your IP immediately.
429 Too Many RequestsRate LimitedYou are sending requests too quickly. Action: Slow down your scraper (increase delays) and rotate your IP.
500 Internal Server ErrorServer ErrorThe target website’s server has an internal problem. Action: Retry the request after a short delay.
503 Service UnavailableService UnavailableThe target website is overloaded or down for maintenance. Action: Retry the request after a longer delay (e.g., 15-30 minutes).
⌘I