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

​

REQS001 Requests To This Domain Are Forbidden

Problem: Requests to this URL are forbidden.

The restricted categories (banks, payment processors, government sites, and similar) describe Zenrows’ access policy. They are not a complete, per-domain list you can check a URL against: a domain matching one of these categories is not automatically blocked. The only way to confirm a domain is blocked is a 400 response with "code": "REQS001" in the body. A 400 with a different code, such as REQ_INVALID_PARAMS (for example, sending js_render or premium_proxy alongside mode=auto), is a separate error: it means the request parameters need changing, not that the domain is blocked.

Solution:

1. Read the code field in the response body: only REQS001 confirms this domain is blocked
2. Review our target sites’ access restrictions and user behavior guidelines for the categories we restrict
3. Try using a different domain that provides similar data
4. 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

Problem: The requested URL domain needs JavaScript rendering and/or Premium Proxies due to its high-level security defenses. This requirement is set per domain (or per URL pattern) and checked before Zenrows fetches the page, so a request that is missing the required parameters is rejected immediately and is not charged.

Solution:

1. Read the error message to understand the specific requirements for the domain
2. Either add the required parameters (js_render=true or antibot=true for JavaScript rendering, and/or premium_proxy=true), or use Adaptive Stealth Mode (mode=auto), which picks the configuration for you and never returns REQS002
3. Send those parameters on your first request to that domain rather than starting with a cheaper configuration and retrying on error: a lighter request keeps returning REQS002 until the domain’s requirements are met, so there’s no cost advantage to trying it first

​

REQS004 Invalid Params Provided

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) 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

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:

css_extractor={
  "title": "h1.product-title",
  "price": "span.product-price"
}

​

REQS006 Invalid CAPTCHA Solver Key

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

Solution:

1. Verify your CAPTCHA solver API key in your account integrations page

   Open integration settings

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

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). 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

​

AUTH001 API Key Missing

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

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

Solution:

1. Copy your API key directly from the Zenrows Playground

   Open the Playground

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

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

Solution:

1. Verify you’re using the correct API key from your Zenrows Playground

   Open the Playground

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

​

AUTH004 Usage Exceeded

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.

An unclaimed agent account is the exception: it is not renewed, and once its first billing period ends, requests answer AUTH005 until a person claims it. Claiming starts a new billing period. See Agent signup and unclaimed accounts.

Not to be confused with 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.

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 or upgrade in the Zenrows Plans page.

   Open billingSee plans

4. For temporary needs or punctual issues, contact our support team.

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 Zenrows Browser usage 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.

​

AUTH005 API Key Is No Longer Valid

Problem: This apikey has reached its validity period.

An unclaimed agent account (one an agent created with no human present, see Agent signup and unclaimed accounts) answers AUTH005 once its first billing period ends, because it is not renewed. A person claiming the account starts a new billing period.

Solution:

1. Check your subscription in the Zenrows Billing page

   Open billing

2. Check if your account is active and working, you can perform a request from the Playground itself

   Open the Playground

3. Contact support if you believe there is an issue with your account

​

AUTH010 Feature Is Not Included In Plan

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

Solution:

1. Review the features included in each plan
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

Problem: This account does not have an active subscription.

Solution:

1. Purchase a subscription plan from the Zenrows plans page

   See 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

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

Problem: This apikey has reached one of its credit caps (per billing period, daily, weekly or monthly). Your other API keys keep working.

Not to be confused with AUTH004, which means your account has no credits left. AUTH014 affects only the key that reached its cap.

Solution:

1. Raise or remove the cap on the API keys page.

   Manage 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

​

AUTH009 User Is Not Verified

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

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

Visit our troubleshooting guide for step-by-step instructions, common causes, and best practices to quickly restore access.

​

REQS007 Extract Refused This Page

Problem: Extract refused this page with a 403. There are three cases, and they have different fixes. The response’s reason field names the case. reason arrives with an upcoming API release; until then, tell the cases apart by the title. None of them is charged, for either the Fetch or the Extract part, and none returns the raw HTML.

reason	title starts with	What it means
domain_not_prepared	Extract is not prepared for the requested domain	Nothing is prepared for this domain yet.
page_not_recognised	Extract did not recognise this page on	The domain is prepared, but Extract did not recognise this page as one it can extract. It is usually a page with nothing to extract, such as a home page; sometimes a transient failure kept Extract from trying. It does not mean a page type is missing: on a prepared domain, Extract learns a new page type on its first request.
domain_not_enabled	Extract is not enabled for the requested domain	Extract is not enabled for this site.

Solution for domain_not_prepared:

1. Prepare the domain with POST /v1/extract/prepared-domains and 1 to 5 example URLs, including this one. One works; we recommend 3 or more of the same page type (e.g. 3 product pages). Preparing takes a few minutes, costs no credits, and uses one slot of your monthly allowance
2. Poll GET /v1/extract/prepared-domains/{domain} about every 30 seconds until status is ready, then retry
3. Meanwhile, use css_extractor, which works on any website without preparation

Solution for page_not_recognised:

1. Try a product, article or listing page on the same site instead
2. If this page should work, retry it once in a few minutes. Don’t retry in a loop
3. Otherwise, extract it with css_extractor and explicit selectors

Preparing the domain again does not change this answer: resubmitting a prepared domain returns its existing ready record.

Solution for domain_not_enabled: Preparing the domain does not change this answer. Use css_extractor, or contact support to have the site enabled.

Preparation is per domain, not per account: once a domain is prepared it works for every Zenrows API key, and changing or upgrading your plan does not affect this error. The domain is the host, without a leading www.: www.example.com is prepared as example.com, but es.wikipedia.org and pt.wikipedia.org are prepared separately.

​

404 Not Found

​

RESP002 Page Not Found

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

RESP002 and 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.

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

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

This returns an HTTP 404, the same status as 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.

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

​

REQS005 Method Not Allowed

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

​

AUTH007 Invalid Proxy-Authorization Header

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

​

RESP005 Response Size Exceeded The Limit

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

Looking for ways to handle large responses? Check out our troubleshooting guide for practical strategies, examples, and tips to work within response size limits.

​

422 Unprocessable Entity

​

RESP001 Could Not Get Content

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:

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 for an example

Using mode=auto? Adaptive Stealth Mode sets js_render and premium_proxy for you, and rejects the request with a 400 if you set either yourself. You can still set proxy_country if the site is region-restricted, or add original_status=true to see the site’s own status code. If a URL keeps returning 422 under mode=auto, drop mode=auto and retry with js_render=true&premium_proxy=true, plus proxy_country if needed, then work through the steps above.

​

no_data_extracted Extract Found No Data On This Page

Problem: Extract knows this page type and applied its extraction, but none of the fields came back filled. With extract_fields, that means the fields you asked for exist on this page type but none came back with a value. Names that match nothing are a different error, REQS004. Extract never answers 200 with an empty parsed object: it returns this error instead. The request is not charged, neither the Fetch nor the Extract part, and the raw HTML is not returned.

Solution:

1. Make sure the page rendered fully. Some sites need js_render=true, and a short wait or a wait_for selector so the content loads before extraction. A block or challenge page usually returns blocked_document instead, but one that gets past that check can land here, so add premium_proxy=true on protected sites
2. If you use extract_fields, omit it to check whether other fields on the page have values
3. If the page renders fully and still returns this error, contact support with the URL

Here Extract recognised the page and ran on it, but no field came back filled. With REQS007, Extract did not run at all: the domain is not prepared, or Extract did not recognise the page. The code is the lowercase no_data_extracted.

​

blocked_document Extract Could Not Read This Page

Problem: An Extract request fetched a page, but it was not the real page, so Extract refused to parse it. The response’s title names the domain, and its detail says what was wrong with the page, usually one of these:

• The page had no real content: it looked like a bot challenge, a block page, or a page that had not finished loading
• The site answered with an error or block page instead of the page itself

The request is not charged.

Solution:

1. If you aren’t already, retry with js_render=true and/or premium_proxy=true, so the real page is fetched
2. Or use Adaptive Stealth Mode (mode=auto), which picks the configuration for you
3. If the site answered with an error or block page, check that the URL is correct

​

424 Failed Dependency

​

RESP006 Failed To Solve CAPTCHA

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

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

​

AUTH006 Concurrency Exceeded

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 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

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

​

CTX0001 Context Cancelled

Problem: The request was canceled before it finished, almost always because the client closed the connection, typically when its timeout fired. If Zenrows’ own time limit is reached instead, you get CTX0002 (504).

This is the error behind HTTP 499. It shows up most often on slow, JavaScript-heavy pages with js_render and premium_proxy enabled, when the client timeout is too short. Requests that end with this error aren’t charged.

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
4. Retry the request with a longer client timeout

​

ERR0001 Unknown Error

Problem: An internal error occurred.

Solution:

1. Retry the request after a short delay (10-30 seconds)
2. Check the Zenrows status page 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

Problem: An unexpected internal error occurred.

Solution:

1. Retry the request after a short delay (10-30 seconds)
2. Check the Zenrows status page 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

​

RESP003 Could Not Parse Content

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

​

RESP009 Service Temporarily At Capacity

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

On an Extract request, RESP009 has two meanings, and the response’s title says which. Extract could not finish this page right now: retry in a minute. Extract is at capacity for new pages right now: Extract has used its capacity for preparing pages it has not seen before, so retry later; pages it already knows keep working. Neither is charged.

​

504 Gateway Timeout

​

CTX0002 Operation Timeout Exceeded

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

Batch and the Extract prepared-domains 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, except no_data_extracted, blocked_document and the three limits on learning new page types in this table (cold_budget_domain_allowance, cold_budget_concurrent_generations and cold_budget_exceeded). For Batch, see how to handle each one in the error handling reference.

HTTP	code	Meaning
400	invalid_argument	Batch: validation failed, for example too many tasks, a bad schedule or an Idempotency-Key over 128 characters; invalid_tasks[] lists {index, reason, value} for each bad task. Extract: the request body is missing or malformed; detail says what, and reason carries a tag such as invalid_domain.
400	invalid_external_id	Batch: an external_id must be 1 to 128 characters of letters, digits, ., _, or -. Also appears as a per-task reason in invalid_tasks[].
400	metadata_too_large	Batch: metadata allows up to 20 entries, each value up to 1,024 bytes (UTF-8), and 4,096 bytes of keys and values in total. Also appears as a per-task reason.
400	metadata_key_invalid	Batch: a metadata key must be 1 to 64 characters, each a letter, digit, ., _, or -. Also appears as a per-task reason.
400	invalid_argument with invalid_tasks[].reason method_param_conflict	Batch: a POST task can’t use js_render=true, js_instructions, or json_response=true, whether it sets them itself or inherits them from the job. js_render=false and json_response=false are allowed; omit js_instructions when you don’t need it.
400	unsupported_scheme	Batch, as a per-task reason: the URL isn’t http or https.
400	malformed_url	Batch, as a per-task reason: the URL can’t be parsed.
400	missing_host	Batch, as a per-task reason: the URL has no host.
400	unsupported_method	Batch, as a per-task reason: the task’s method isn’t GET or POST, or POST tasks aren’t enabled on the API you called.
400	body_not_allowed	Batch, as a per-task reason: a body was sent on a task that isn’t POST.
400	body_too_large	Batch, as a per-task reason: a POST task’s body is over 16 KiB.
400	body_malformed	Batch, as a per-task reason: the task’s body can’t be encoded as a request body.
400	url_too_long	Batch: a URL is longer than 2,048 bytes. On a webhook, the url is too long; on a task, it appears as a per-task reason in invalid_tasks[].
400	callback_url_must_be_https	Batch: the webhook url must be a valid https URL with a host.
400	callback_url_unresolvable	Batch: the webhook url’s host didn’t resolve.
400	webhook_signing_requires_active_key	Batch: a webhook asks for signature: true, but the account has no active HMAC key. Create one with POST /v1/hmac/keys/rotate first.
401	unauthenticated	Missing or invalid API key.
401	subscription_inactive	Batch: the API key is valid, but the subscription is past due, unpaid, incomplete or paused. detail reads “Subscription is not active.” Update your payment method, finish the pending payment, or resume the subscription in Billing, or in Azure Marketplace if you subscribed there, then retry. Before this code existed, these responses used unauthenticated with the same detail.
402	payment_required	No credits available.
402	api_key_cap_reached	The API key reached one of its credit caps. The Batch equivalent of AUTH014. See API key credit caps and Batch.
403	permission_denied	Batch: the Batch API isn’t enabled for this account. Contact support.
404	not_found	Batch: job, run, task, export or webhook missing, deleted, or not owned by your account. Extract: this account has never submitted that domain.
404	file_input_not_found	Batch: the file_input_id doesn’t exist or its 24-hour upload slot expired. Create a new upload.
409	conflict	Batch: the job can’t take this action right now. The detail says which case: the operation isn’t supported on a scheduled job, the API key that created the job is no longer valid (submit it as a new job), or a concurrent change (retry).
409	run_not_terminal	Batch: on a rerun, the previous run is still in progress (call /stop first), or its task ingestion was interrupted and can’t be rerun (delete the job and submit it again). On adding tasks, the job’s initial task ingestion hasn’t finished yet (retry shortly).
409	idempotency_key_conflict	Batch: the Idempotency-Key was reused with a different body (or a different ?status= on a rerun), or while an earlier request with it is still in progress. A same-key, same-body retry of a submit, rerun or add-tasks call that succeeded replays the original response instead. See Idempotency.
409	job_not_open	Batch: tasks can only be added to an open job’s first run. Also returned when the job was closed while the call was adding its tasks; none of them are added.
409	last_batch_received	Batch: the job already received its last_batch: true call, so it takes no more tasks.
409	run_not_stoppable	Batch: the latest run already finished, so it can’t be stopped, paused, or resumed.
409	no_prior_run	Batch: there’s no previous run with tasks to rerun.
409	no_matching_tasks	Batch: no task in the previous run matches the ?status= filter of a partial rerun.
409	run_has_descendants	Batch: newer runs reuse results from this run. Delete those runs first, or delete the whole job.
409	task_not_ready	Batch: the task is still pending or processing, so it has no content yet. Poll again shortly.
409	candidate_pending	Batch: a new HMAC key is already pending. Finalize or cancel it before rotating again.
409	no_candidate	Batch: there’s no pending HMAC key to finalize.
409	file_input_not_uploaded	Batch: the CSV upload slot exists, but the file hasn’t been uploaded to it yet.
409	file_input_unsupported_for_job_type	Batch: file_input_id works only on closed regular jobs and scheduled jobs.
409	partial_rerun_window_expired	Batch: a partial rerun (?status=) was requested more than 10 days after the run it retries started. Start a full rerun instead.
409	in_progress	Extract: that domain already has a preparation running. Poll its status instead of resubmitting.
409	idempotency_conflict	Extract: the same Idempotency-Key was reused with a different body.
410	result_expired	Batch: the task’s content aged past its 14-day availability window, counted from the task’s updated_at; its result row reads status: "expired". Rerun the job to scrape it again. Also returned when you poll a results export more than 12 hours after it was created; start a new export.
422	(on /content)	Task failed; the body is the stored error.
429	quota_exceeded	Batch: an account limit was reached. The detail says which: 3 active jobs (shared with Crawl; a job counts until it’s deleted, or closed with its latest run ended), 5 scheduled jobs, or 100,000 tasks in an open job. The active and scheduled limits are defaults; contact support to raise them. The 100,000-task limit on an open job is fixed.
429	out_of_allowance	Extract: no domain preparation slots left this month. Check GET /v1/extract/prepared-domains/allowance.
429	cold_budget_domain_allowance	Extract (extract=auto): this page needed Extract to learn a new page type on a prepared domain, and this account has reached its limit of domains it can do that on in the current window. The detail gives how many are used and the limit. Pages Extract already recognises keep working. Not charged. Wait for the next window, or contact support for a higher limit.
429	cold_budget_concurrent_generations	Extract (extract=auto): Extract is learning too many new page types for this account at the same time. Pages Extract already recognises keep working. Not charged. Retry shortly.
429	cold_budget_exceeded	Extract (extract=auto): the limit on learning new page types has been reached. Pages Extract already recognises keep working. Not charged. Retry later, or contact support if you need a higher limit.
503	overloaded	Extract prepared-domains: submissions are paused because today’s preparation capacity is used up, or the queue is full. The attempt does not count against your allowance. Retry later.
503	disabled	Extract prepared-domains: domain submissions are temporarily unavailable. Retry later.
503	gateway_unreachable	Batch, on a failed task’s error: the request couldn’t reach the scraping service. Rerun the failed tasks.
500 / 503	internal	Batch: a server-side failure. Retry with a backoff, with the same Idempotency-Key on a submit, rerun or add-tasks call.
501	not_implemented	Batch: the endpoint isn’t available in this environment.
504	gateway_timeout	Batch, on a failed task’s error: the scraping service didn’t answer within the attempt’s time limit. Rerun the failed tasks.

In a Batch 400 invalid_argument, each invalid_tasks[] entry names the task’s index, a reason and, when there is one, the offending value. URL, metadata, ID, and request-method problems use these reasons: unsupported_scheme, malformed_url, missing_host, url_too_long, metadata_too_large, metadata_key_invalid, invalid_external_id, unsupported_method, body_not_allowed, body_too_large, body_malformed, and method_param_conflict. A bad scraping parameter uses unknown_param (Batch doesn’t accept that key) or invalid_param_value, and value names the parameter.