API Error Codes
Understanding the ZenRows® Universal Scraper API 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 the Universal Scraper API 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.
Solution:
- Check our target sites’ access restrictions and user behavior guidelines to see if the domain is explicitly blocked
- Try using a different domain that provides similar data
- 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.
Solution:
- Read the error message to understand the specific requirements for the domain
- Add
js_render=true
and/orpremium_proxy=true
parameters to your request, depending on the domain’s requirements
REQS004 Invalid Params Provided
Problem: Some parameters or even the URL are invalid or not properly encoded.
Solution:
- Read the error message to understand the specific issue
- Ensure your URL is properly URL-encoded (check our guide on encoding URLs) or the http you use is doing it for you
- Validate that all parameter values match the expected types (boolean, string, etc.)
- Remove any invalid or unsupported parameters from your request
- 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:
- Check your CSS selector syntax for errors (like missing brackets or quotes)
- Simplify complex selectors that might be causing issues
- Test your CSS selector on the actual page using browser developer tools first (
document.querySelector('.your-selector')
) - If extracting multiple elements, ensure your JSON structure follows the correct format:
REQS006 Invalid CAPTCHA Solver Key
Problem: The configured CAPTCHA solver integration API key is invalid.
Solution:
- Verify your CAPTCHA solver API key in your account integrations page
- Check that your CAPTCHA solver account has sufficient funds
- Confirm the CAPTCHA solver service is operational through their status page
- 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 on the site’s config or certificate, not an error ZenRows can solve or bypass.
Solution:
- Check if the target website is accessible from your browser
- If you’re using geolocation, try a different country as the site might only be available in specific regions
- Wait a few minutes and retry as the issue might be temporary
- 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:
- Add the
apikey
parameter to your request - Check your code to ensure the apikey is being included in every request
- For API clients like Axios or Requests, set up default parameters to include your API key automatically
- 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:
- Copy your API key directly from the ZenRows Builder
- Ensure no extra spaces or characters were accidentally included
- Check for any string formatting or concatenation issues in your code
- 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:
- Verify you’re using the correct API key from your ZenRows Builder
- Check if your API key has been revoked or regenerated recently
- Ensure your account is active and working, you can perform a request from the Builder itself
- For team accounts, confirm with your administrator that the key is still valid
402 Payment Required
AUTH004 Usage Exceeded
Problem: This apikey
has no more usage remaining.
Solution:
- Top up your account in the ZenRows Billing page
- Upgrade your plan in the ZenRows Plans page
- Check your current usage to see if you’re approaching limits before they’re reached
- For temporary needs or puntual issues, contact our support team
AUTH005 API Key Is No Longer Valid
Problem: This apikey
has reached its validity period.
Solution:
- Check your subscription in the ZenRows Billing page
- Check if your account is active and working, you can perform a request from the Builder itself
- 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:
- Review the features included in each plan
- Upgrade to a plan that includes the feature you need
- Modify your code to avoid using premium features if you don’t upgrade
- 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:
- Purchase a subscription plan from the ZenRows plans page
- Check for any failed payment attempts in your account history
- Verify your payment method details are correct
- Contact our support team if you believe there is an issue with your account
AUTH012 Subscription Does Not Allow To Use The Product
Problem: This account subscription does not allow to use this service.
Solution:
- Check which ZenRows products your subscription includes
- Upgrade to a plan that includes the product you’re trying to use
- Ensure you’re using the correct API endpoint for your subscription
- Contact our support team if you believe there is an issue with your account
403 Forbidden
AUTH009 User Is Not Verified
Problem: This apikey
belongs to a user that has not verified the email account.
Solution:
- Check your email inbox (including spam folder) for a verification email
- Request a new verification email
- Ensure your email address is entered correctly in your profile
- 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:
- Wait a few minutes before retrying requests
- Implement error handling in your code to prevent excessive failed requests
- Use exponential backoff when retrying failed requests
- If using the service in a high-traffic environment, consider implementing a queue system to manage request rates
404 Not Found
RESP002 Page Not Found
Problem: The requested URL page returned a 404 HTTP Status Code.
Solution:
- Verify the URL exists by opening it in a browser
- Check for typos or encoding issues in the URL
- If the page was recently available, it might have been moved or deleted
- For dynamic sites, try adding
js_render=true
as some 404 pages are generated via JavaScript - 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.
Solution:
- Verify the domain exists by checking in your browser
- Check for typos in the domain name
- If using an IP address, ensure it’s correctly formatted
- If the domain is new or rarely accessed, DNS propagation might still be in progress
- Try using premium proxies and geolocation since the domain might be available only in certain countries
- 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:
- Change your request method to one of the allowed methods: GET, POST, or PUT
- For complex requests, consider breaking them down into multiple simpler requests
- 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:
- Ensure the Proxy-Authorization header is a base64 encoded string of
<apikey>:<params>
- Check your base64 encoding function for errors or incorrect character handling
- 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:
- Request specific parts of the page using CSS selectors instead of the entire page
- Split large pages into multiple smaller requests by targeting specific sections
- Use pagination parameters if available on the target site
- If using JSON Response, the full response will be considered for the size limit - try revoming it and see if it works
422 Unprocessable Entity
RESP001 Could Not Get Content
Problem: The service couldn’t get the content.
Solution:
- Add
js_render=true
as the site might require JavaScript to load content - Enable
premium_proxy=true
if the site has anti-bot measures - Try adding geolocation to the request set to a country where the site is available
- Increase wait time with
wait=5000
or higher if content loads slowly - Check the error’s body for more specific details about the failure
- Try using custom headers with a referer to mimic a real browser:
424 Failed Dependency
RESP006 Failed To Solve CAPTCHA
Problem: The CAPTCHA solver provider was unable to solve the CAPTCHA detected in the page.
Solution:
- Check your CAPTCHA solver service account for sufficient balance
- Try adding premium proxies to the request
- Implement retry logic with increasing wait times between attempts
429 Too Many Requests
AUTH006 Concurrency Exceeded
Problem: The concurrency limit was reached.
Solution:
- Implement a queue system in your code to limit concurrency requests
- Monitor the
Concurrency-Remaining
header to adjust your request rate dynamically - Increase wait times between batches of requests
- For high-volume scraping needs, upgrade to a plan with higher concurrency limits
- Learn more about how ZenRows concurrency works and implement the provided code examples
- 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:
- Implement exponential backoff between requests
- Distribute requests evenly over time rather than sending them in bursts
- Set up a queue system with configurable delay between requests
- For time-sensitive projects, consider upgrading to a plan with higher rate limits
- Monitor usage patterns to identify and optimize peak request periods
500 Internal Server Error
CTX0001 Context Cancelled
Problem: The request was canceled from the client’s side.
Solution:
- Check your client’s timeout settings - we recommend not setting a timeout below 3 minutes
- If you’re canceling requests manually, review your cancellation logic
- Ensure your network connection is stable during the entire request
ERR0001 Unknown Error
Problem: An internal error occurred.
Solution:
- Retry the request after a short delay (10-30 seconds)
- Check the ZenRows status page for any ongoing issues
- Implement error logging to capture the full error response for troubleshooting
- If the error persists, contact support with details of your request
ERR0000 Unknown Error
Problem: An unexpected internal error occurred.
Solution:
- Retry the request after a short delay (10-30 seconds)
- Check the ZenRows status page for any ongoing issues
- Implement error logging to capture the full error response for troubleshooting
- 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:
- Remove the
autoparse
parameter and process the raw HTML response - Contact support with details of your request if the issue persists
504 Gateway Timeout
CTX0002 Operation Timeout Exceeded
Problem: The request exceeded the maximum allowed time and was aborted.
Solution:
- Check if the target website is slow or unresponsive in a browser
- Reduce the complexity of your request if using JS Instructions
- Try adding premium proxies to the request or geolocation to a country where the site is available
- Break complex scraping tasks into smaller, more focused requests
- If the issue persists, contact support with details of your request and use case