> ## Documentation Index > Fetch the complete documentation index at: https://docs.2extract.com/llms.txt > Use this file to discover all available pages before exploring further. # Error Handling & Response Codes > Understand the different HTTP response codes our proxy gateway can return and learn how to debug common issues. 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` 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**](https://2extract.com/app/billing) 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).** |