> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenrows.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Codes

> Complete list of Zenrows API error codes with troubleshooting steps, status code meanings, and solutions for common request failures.

Understanding the Zenrows Fetch error codes is crucial for troubleshooting and optimizing your interactions with Zenrows. Below are common errors you may encounter, along with explanations and recommended actions.

Each error code corresponds to specific conditions encountered during Fetch usage, from authentication problems to request handling and server responses.

## 400 Bad Request<span style={{scrollMarginTop: 80}} id="400" />

### REQS001 Requests To This Domain Are Forbidden<span style={{scrollMarginTop: 80}} id="REQS001" />

**Problem:** Requests to this URL are forbidden.

**Solution:**

1. Check our [target sites' access restrictions and user behavior guidelines](/forbidden-sites) to see if the domain is explicitly blocked
2. Try using a different domain that provides similar data
3. If you need to scrape this specific domain for a legitimate business purpose, contact our support team to discuss potential options

### REQS002 Request Requirements Unsatisfied<span style={{scrollMarginTop: 80}} id="REQS002" />

**Problem:** The requested URL domain needs JavaScript rendering and/or Premium Proxies due to its high-level security defenses.

**Solution:**

1. Read the error message to understand the specific requirements for the domain
2. Add `js_render=true` and/or `premium_proxy=true` parameters to your request, depending on the domain's requirements

### REQS004 Invalid Params Provided<span style={{scrollMarginTop: 80}} id="REQS004" />

**Problem:** Some parameters or even the URL are invalid or not properly encoded.

**Solution:**

1. Read the error message to understand the specific issue
2. Ensure your URL is properly URL-encoded (check our [guide on encoding URLs](/fetch/faq#how-to-encode-urls)) or the http you use is doing it for you
3. Validate that all parameter values match the expected types (boolean, string, etc.)
4. Remove any invalid or unsupported parameters from your request
5. Check that you are not sending query parameters for the target page as parameters for the API call

### RESP004 CSS Extractor Parameter Is Not Valid<span style={{scrollMarginTop: 80}} id="RESP004" />

**Problem:** The `css_extractor` parameter sent in your request is not valid.

**Solution:**

1. Check your CSS selector syntax for errors (like missing brackets or quotes)
2. Simplify complex selectors that might be causing issues
3. Test your CSS selector on the actual page using browser developer tools first (`document.querySelector('.your-selector')`)
4. If extracting multiple elements, ensure your JSON structure follows the correct format:

```js theme={"dark"}
css_extractor={
  "title": "h1.product-title",
  "price": "span.product-price"
}
```

### REQS006 Invalid CAPTCHA Solver Key<span style={{scrollMarginTop: 80}} id="REQS006" />

**Problem:** The configured CAPTCHA solver integration API key is invalid.

**Solution:**

1. Verify your CAPTCHA solver API key in your [account integrations](https://app.zenrows.com/settings/integrations) page
2. Check that your CAPTCHA solver account has sufficient funds
3. Confirm the CAPTCHA solver service is operational through their status page
4. Try re-generating a new API key from your CAPTCHA solver service

### RESP008 Non-Retryable Error not related to Zenrows<span style={{scrollMarginTop: 80}} id="RESP008" />

**Problem:** The target returned an error tied to the site's own configuration or certificate, not something Zenrows can solve or bypass by changing request parameters. Zenrows does not retry RESP008 automatically, but the underlying condition can be temporary on the target's side.

**Solution:**

1. Check if the target website is accessible from your own browser or host
2. If you're using geolocation, try a different country as the site might only be available in specific regions
3. If the error reports a certificate problem but the certificate checks out fine when you access the site directly, the condition may be intermittent on the target's side. Wait a few minutes and retry once or twice. Don't retry in a loop, because repeated 400 errors can trigger a temporary IP block ([BLK0001](#BLK0001)). If it keeps failing, contact support with the `X-Request-Id` response header
4. For SSL certificate issues, try accessing the HTTP version of the site if available

## 401 Unauthorized<span style={{scrollMarginTop: 80}} id="401" />

### AUTH001 API Key Missing<span style={{scrollMarginTop: 80}} id="AUTH001" />

**Problem:** No `apikey` information was sent in your request.

**Solution:**

1. Add the `apikey` parameter to your request
2. Check your code to ensure the apikey is being included in every request
3. For API clients like Axios or Requests, set up default parameters to include your API key automatically
4. Verify the API endpoint structure - the key should be sent as a query parameter to the API endpoint

### AUTH002 Invalid API Key<span style={{scrollMarginTop: 80}} id="AUTH002" />

**Problem:** The `apikey` sent does not match the expected format.

**Solution:**

1. Copy your API key directly from the [Zenrows Playground](https://app.zenrows.com/fetch)
2. Ensure no extra spaces or characters were accidentally included
3. Check for any string formatting or concatenation issues in your code
4. If using environment variables, verify they're loading correctly

### AUTH003 API Key Not Found<span style={{scrollMarginTop: 80}} id="AUTH003" />

**Problem:** The `apikey` sent in your request is not valid.

**Solution:**

1. Verify you're using the correct API key from your [Zenrows Playground](https://app.zenrows.com/fetch)
2. Check if your API key has been revoked or regenerated recently
3. Ensure your account is active and working, you can perform a request from the Playground itself
4. For team accounts, confirm with your administrator that the key is still valid

## 402 Payment Required<span style={{scrollMarginTop: 80}} id="402" />

### AUTH004 Usage Exceeded<span style={{scrollMarginTop: 80}} id="AUTH004" />

**Problem:** This `apikey` has spent its credit allowance for the current billing period.

**This is not a permanent block.** The allowance renews at the end of the period, and requests succeed again from then on with no action on your part. Topping up or upgrading is how you carry on *before* that.

<Note>
  Not to be confused with [AUTH006](#AUTH006), the concurrency limit — too many requests *at once*, rather than too many across the period. AUTH006 clears in seconds; AUTH004 clears at the period boundary.
</Note>

**Solution:**

1. Check where you stand and when the period ends: call `/v1/subscriptions/self/details` with your API key in the `X-API-Key` header, or run `zenrows usage`. Neither counts against your concurrency limit, so both are safe to call from a script right after a failure.
2. If you can wait for the renewal date, retry after it. Retrying sooner returns AUTH004 again unless the allowance itself has changed — a top-up or a plan upgrade raises it immediately, mid-period.
3. To continue now, top up in the [Zenrows Billing page](https://app.zenrows.com/billing) or upgrade in the [Zenrows Plans page](https://app.zenrows.com/plans).
4. For temporary needs or punctual issues, contact our support team.

<Tip>
  **Writing a client or agent?** Read `usage_percent` and `period_ends_at` from `/v1/subscriptions/self/details` before a large run, and back off rather than retry when you see AUTH004. A Fetch request costs between 1 and 25 credits depending on `js_render` and `premium_proxy`, and Browser Sessions and residential bandwidth draw on the same balance at their own rates, so a run can consume far more of the allowance than its request count suggests.
</Tip>

### AUTH005 API Key Is No Longer Valid<span style={{scrollMarginTop: 80}} id="AUTH005" />

**Problem:** This `apikey` has reached its validity period.

**Solution:**

1. Check your subscription in the [Zenrows Billing page](https://app.zenrows.com/billing)
2. Check if your account is active and working, you can perform a request from the [Playground](https://app.zenrows.com/fetch) itself
3. Contact support if you believe there is an issue with your account

### AUTH010 Feature Is Not Included In Plan<span style={{scrollMarginTop: 80}} id="AUTH010" />

**Problem:** The requested feature is not included in your subscription plan.

**Solution:**

1. Review the [features included in each plan](https://www.zenrows.com/pricing)
2. Upgrade to a plan that includes the feature you need
3. Modify your code to avoid using premium features if you don't upgrade
4. Contact our support team if you believe there is an issue with your account

### AUTH011 No Subscription Found<span style={{scrollMarginTop: 80}} id="AUTH011" />

**Problem:** This account does not have an active subscription.

**Solution:**

1. Purchase a subscription plan from the [Zenrows plans page](https://app.zenrows.com/plans)
2. Check for any failed payment attempts in your account history
3. Verify your payment method details are correct
4. Contact our support team if you believe there is an issue with your account

### AUTH012 Subscription Does Not Allow Use Of The Product<span style={{scrollMarginTop: 80}} id="AUTH012" />

**Problem:** This account subscription does not allow the use of this service.

**Solution:**

1. Check which Zenrows products your subscription includes
2. Upgrade to a plan that includes the product you're trying to use
3. Ensure you're using the correct API endpoint for your subscription
4. Contact our support team if you believe there is an issue with your account

### AUTH014 API Key Credit Cap Reached<span style={{scrollMarginTop: 80}} id="AUTH014" />

**Problem:** This `apikey` has reached one of its [credit caps](/first-steps/api-key-credit-caps) (per billing period, daily, weekly or monthly). Your other API keys keep working.

<Note>
  Not to be confused with [AUTH004](#AUTH004), which means your account has no credits left. AUTH014 affects only the key that reached its cap.
</Note>

**Solution:**

1. Raise or remove the cap on the [API keys page](https://app.zenrows.com/settings/api-keys).
2. Or wait for the cap's window to reset. Daily, weekly and monthly caps reset in UTC; the billing-period cap resets with your billing period.

## 403 Forbidden<span style={{scrollMarginTop: 80}} id="403" />

### AUTH009 User Is Not Verified<span style={{scrollMarginTop: 80}} id="AUTH009" />

**Problem:** This `apikey` belongs to a user that has not verified the email account.

**Solution:**

1. Check your email inbox (including spam folder) for a verification email
2. Request a new verification email
3. Ensure your email address is entered correctly in your profile
4. Contact support if you continue to have verification issues

### BLK0001 IP Address Blocked<span style={{scrollMarginTop: 80}} id="BLK0001" />

**Problem:** Your IP address has been blocked for exceeding the maximum error rate allowed.

**Solution:**

1. Wait a few minutes before retrying requests
2. Implement error handling in your code to prevent excessive failed requests
3. Use exponential backoff when retrying failed requests
4. If using the service in a high-traffic environment, consider implementing a queue system to manage request rates

<Tip>
  Visit our [troubleshooting guide](/fetch/troubleshooting/ip-address-blocked) for step-by-step instructions, common causes, and best practices to quickly restore access.
</Tip>

### REQS007 Extract Is Not Prepared For This Domain<span style={{scrollMarginTop: 80}} id="REQS007" />

**Problem:** You asked Extract for a domain it has not been prepared for. The message names the domain.

**Solution:**

1. Ask for the domain with [`POST /v1/extract/prepared-domains`](/extract/endpoints#getting-a-domain-prepared), then retry once it reports `ready`
2. Call [`GET /v1/extract/domains`](/extract/endpoints#which-domains-extract-serves) to see what Extract serves right now
3. Use [`css_extractor`](/fetch/features/css-extractor) meanwhile, which works on any website without preparation. The deprecated [`autoparse`](/fetch/features/autoparse) parameter also still works, but new integrations should not start there

<Note>
  Preparation is per domain, not per account: once a domain is prepared it works for every Zenrows API key. Changing or upgrading your plan does not affect this error.
</Note>

## 404 Not Found<span style={{scrollMarginTop: 80}} id="404" />

### RESP002 Page Not Found<span style={{scrollMarginTop: 80}} id="RESP002" />

**Problem:** The requested URL page returned a 404 HTTP Status Code.

<Note>
  RESP002 and [RESP007](#RESP007) both return HTTP 404. Check the `code` field in the JSON error body to tell them apart: RESP002 means the page was not found on a domain that resolves, and RESP007 means the domain does not resolve.
</Note>

**Solution:**

1. Verify the URL exists by opening it in a browser
2. Check for typos or encoding issues in the URL
3. If the page was recently available, it might have been moved or deleted
4. For dynamic sites, try adding `js_render=true` as some 404 pages are generated via JavaScript
5. Note that these requests are billed

### RESP007 Site Not Found<span style={{scrollMarginTop: 80}} id="RESP007" />

**Problem:** The requested target domain could not be resolved, or there is no DNS record associated with it.

<Note>
  This returns an HTTP 404, the same status as [RESP002](#RESP002). Check the `code` field in the JSON error body: `RESP007` means the domain does not resolve (DNS failure), and `RESP002` means the page was not found. A retry will not change the result.
</Note>

**Solution:**

1. Verify the domain exists by checking in your browser
2. Check for typos in the domain name
3. If using an IP address, ensure it's correctly formatted
4. If the domain is new or rarely accessed, DNS propagation might still be in progress
5. Try using premium proxies and geolocation since the domain might be available only in certain countries
6. Note that these requests are billed

## 405 Method Not Allowed<span style={{scrollMarginTop: 80}} id="405" />

### REQS005 Method Not Allowed<span style={{scrollMarginTop: 80}} id="REQS005" />

**Problem:** The HTTP verb used to access this page is not allowed.

**Solution:**

1. Change your request method to one of the allowed methods: GET, POST, or PUT
2. For complex requests, consider breaking them down into multiple simpler requests
3. Check if the endpoint you're trying to access has specific method requirements

## 407 Proxy Authentication Required<span style={{scrollMarginTop: 80}} id="407" />

### AUTH007 Invalid Proxy-Authorization Header<span style={{scrollMarginTop: 80}} id="AUTH007" />

**Problem:** The Proxy-Authorization header sent does not match the expected format.

**Solution:**

1. Ensure the Proxy-Authorization header is a base64 encoded string of `<apikey>:<params>`
2. Check your base64 encoding function for errors or incorrect character handling
3. Try API calls instead of proxy mode to ensure that the API key and account are working properly

## 413 Content Too Large<span style={{scrollMarginTop: 80}} id="413" />

### RESP005 Response Size Exceeded The Limit<span style={{scrollMarginTop: 80}} id="RESP005" />

**Problem:** The response data size is bigger than the maximum allowed download size.

**Solution:**

1. Request specific parts of the page using CSS selectors instead of the entire page
2. Split large pages into multiple smaller requests by targeting specific sections
3. Use pagination parameters if available on the target site
4. If using JSON Response, the full response will be considered for the size limit - try removing it and see if it works

<Tip>
  Looking for ways to handle large responses? Check out our [troubleshooting guide](/fetch/troubleshooting/response-too-large) for practical strategies, examples, and tips to work within response size limits.
</Tip>

## 422 Unprocessable Entity<span style={{scrollMarginTop: 80}} id="422" />

### RESP001 Could Not Get Content<span style={{scrollMarginTop: 80}} id="RESP001" />

**Problem:** The service couldn't get the content.

**Solution:**

1. Add `js_render=true` as the site might require JavaScript to load content
2. Enable `premium_proxy=true` if the site has anti-bot measures
3. Try adding geolocation to the request set to a country where the site is available
4. Increase wait time with `wait=5000` or higher if content loads slowly
5. Check the error's body for more specific details about the failure
6. Try using custom headers with a referer to mimic a real browser:

```js theme={"dark"}
params={
  // ...
  "custom_headers": true,
}
headers={
  "Referer": "https://www.google.com"
}
```

7. If you already use `js_render=true` and `premium_proxy=true` and still get 422 after adding extras, remove `wait`, `wait_for`, and the custom `referer` header, then retest with only those two. Keep `proxy_country` if the site is region-restricted. Some protected sites respond better to the minimal configuration. See the [troubleshooting guide](/fetch/troubleshooting/troubleshooting-guide#still-failing-after-stacking-parameters-retest-with-the-minimal-config) for an example

## 424 Failed Dependency<span style={{scrollMarginTop: 80}} id="424" />

### RESP006 Failed To Solve CAPTCHA<span style={{scrollMarginTop: 80}} id="RESP006" />

**Problem:** The CAPTCHA solver provider was unable to solve the CAPTCHA detected in the page.

**Solution:**

1. Check your CAPTCHA solver service account for sufficient balance
2. Try adding premium proxies to the request
3. Implement retry logic with increasing wait times between attempts

## 429 Too Many Requests<span style={{scrollMarginTop: 80}} id="429" />

<Note>
  When a burst of requests fails together, group the failures by HTTP status and `code` before troubleshooting. A burst can mix [404](#404) and 429 errors, and [AUTH006](#AUTH006) (concurrency) and [AUTH008](#AUTH008) (rate limit) both return 429. Fix each code with its own solution.
</Note>

### AUTH006 Concurrency Exceeded<span style={{scrollMarginTop: 80}} id="AUTH006" />

**Problem:** The concurrency limit was reached.

**Solution:**

1. Implement a queue system in your code to limit concurrency requests
2. Monitor the `Concurrency-Remaining` header to adjust your request rate dynamically
3. Increase wait times between batches of requests
4. For high-volume scraping needs, upgrade to a plan with higher concurrency limits
5. Learn more about [how Zenrows concurrency works](/fetch/features/concurrency) and implement the provided code examples
6. Note that canceled requests on the client side will not release concurrency until the processing is done in the server side - we recommend not setting a timeout below 3 minutes

### AUTH008 Rate Limit Exceeded<span style={{scrollMarginTop: 80}} id="AUTH008" />

**Problem:** The rate limit was reached.

**Solution:**

1. Implement exponential backoff between requests
2. Distribute requests evenly over time rather than sending them in bursts
3. Set up a queue system with configurable delay between requests
4. For time-sensitive projects, consider upgrading to a plan with higher rate limits
5. Monitor usage patterns to identify and optimize peak request periods

## 500 Internal Server Error<span style={{scrollMarginTop: 80}} id="500" />

### CTX0001 Context Cancelled<span style={{scrollMarginTop: 80}} id="CTX0001" />

**Problem:** The request was canceled from the client's side.

**Solution:**

1. Check your client's timeout settings - we recommend not setting a timeout below 3 minutes
2. If you're canceling requests manually, review your cancellation logic
3. Ensure your network connection is stable during the entire request

### ERR0001 Unknown Error<span style={{scrollMarginTop: 80}} id="ERR0001" />

**Problem:** An internal error occurred.

**Solution:**

1. Retry the request after a short delay (10-30 seconds)
2. Check the [Zenrows status page](https://status.zenrows.com/) for any ongoing issues
3. Implement error logging to capture the full error response for troubleshooting
4. If the error persists, contact support with details of your request

### ERR0000 Unknown Error<span style={{scrollMarginTop: 80}} id="ERR0000" />

**Problem:** An unexpected internal error occurred.

**Solution:**

1. Retry the request after a short delay (10-30 seconds)
2. Check the [Zenrows status page](https://status.zenrows.com/) for any ongoing issues
3. Implement error logging to capture the full error response for troubleshooting
4. If the error persists, contact support with details of your request

## 502 Bad Gateway<span style={{scrollMarginTop: 80}} id="502" />

### RESP003 Could Not Parse Content<span style={{scrollMarginTop: 80}} id="RESP003" />

**Problem:** The request failed because the URL could not be automatically parsed.

**Solution:**

1. Remove the `autoparse` parameter and process the raw HTML response
2. Contact support with details of your request if the issue persists

## 503 Service Unavailable<span style={{scrollMarginTop: 80}} id="503" />

### RESP009 Service Temporarily At Capacity<span style={{scrollMarginTop: 80}} id="RESP009" />

**Problem:** All scraping capacity is busy right now. This is a temporary condition on our side.

**Solution:**

1. Retry the request after a short delay; this condition usually clears within seconds as capacity frees up
2. Increase the wait between retries (exponential backoff) and add a small random delay to each one (jitter), so repeated retries do not all arrive at the same instant
3. Treat it like any transient 503: the request is safe to retry
4. If you see it sustained over a longer period, contact support with your account and request details

## 504 Gateway Timeout<span style={{scrollMarginTop: 80}} id="504" />

### CTX0002 Operation Timeout Exceeded<span style={{scrollMarginTop: 80}} id="CTX0002" />

**Problem:** The request exceeded the maximum allowed time and was aborted.

**Solution:**

1. Check if the target website is slow or unresponsive in a browser
2. Reduce the complexity of your request if using JS Instructions
3. Try adding premium proxies to the request or geolocation to a country where the site is available
4. Break complex scraping tasks into smaller, more focused requests
5. If the issue persists, contact support with details of your request and use case

## Batch and Extract error codes<span style={{scrollMarginTop: 80}} id="batch" />

[Batch](/batch/introduction) and the [Extract prepared-domains endpoints](/extract/endpoints) answer errors with lowercase `code` values, and each error's `type` links to its row below. Extract requests made with `extract=auto` use the uppercase codes above, such as [REQS007](#REQS007). For Batch, see how to handle each one in the [error handling reference](/batch/developer-guide-restapi#error-handling-reference).

| HTTP | `code` | Meaning |
| - | - | - |
| 400 | `invalid_argument`<span style={{scrollMarginTop: 80}} id="invalid_argument" /> | Batch: validation failed; `invalid_tasks[]` lists `{index, reason}`. Extract: the request body is missing or malformed; `detail` says what, and `reason` carries a tag such as `invalid_domain`. |
| 401 | `unauthenticated`<span style={{scrollMarginTop: 80}} id="unauthenticated" /> | Missing or invalid API key. |
| 402 | `payment_required`<span style={{scrollMarginTop: 80}} id="payment_required" /> | No credits available. |
| 402 | `api_key_cap_reached`<span style={{scrollMarginTop: 80}} id="api_key_cap_reached" /> | The API key reached one of its [credit caps](/first-steps/api-key-credit-caps). The Batch equivalent of [AUTH014](#AUTH014). See [API key credit caps and Batch](/batch/developer-guide-restapi#api-key-credit-caps-and-batch). |
| 404 | `not_found`<span style={{scrollMarginTop: 80}} id="not_found" /> | Batch: job, run, or task missing or not owned by you. Extract: this account has never submitted that domain. |
| 409 | `conflict`<span style={{scrollMarginTop: 80}} id="conflict" /> / `run_not_terminal`<span style={{scrollMarginTop: 80}} id="run_not_terminal" /> / `idempotency_key_conflict`<span style={{scrollMarginTop: 80}} id="idempotency_key_conflict" /> | State conflict; see `detail`. |
| 409 | `partial_rerun_window_expired`<span style={{scrollMarginTop: 80}} id="partial_rerun_window_expired" /> | Batch: a partial rerun was requested more than 10 days after the original run. Start a full rerun instead. |
| 409 | `in_progress`<span style={{scrollMarginTop: 80}} id="in_progress" /> | Extract: that domain already has a preparation running. Poll its status instead of resubmitting. |
| 409 | `idempotency_conflict`<span style={{scrollMarginTop: 80}} id="idempotency_conflict" /> | Extract: the same `Idempotency-Key` was reused with a different body. |
| 422 | (on `/content`) | Task failed; the body is the stored error. |
| 429 | `quota_exceeded`<span style={{scrollMarginTop: 80}} id="quota_exceeded" /> | Account limit reached, such as the maximum of 3 concurrent active jobs. |
| 429 | `out_of_allowance`<span style={{scrollMarginTop: 80}} id="out_of_allowance" /> | Extract: no domain preparation slots left this month. Check `GET /v1/extract/prepared-domains/allowance`. |
| 503 | `internal`<span style={{scrollMarginTop: 80}} id="internal" /> | Transient; safe to retry with a backoff. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.