Request status codes
You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support). A successful request will be returned with status code 200.
Every response carries an X-Request-Id header, and the errors the API
answers also carry it in the body as request_id. If an error is not
explained here, send us that id with your request at
support@screenshotbase.com and we can look it up.
Error body
Every error is JSON with a human-readable message, a machine-readable error.code (listed below), actions with links that help (upgrade, docs) and, for errors the API answers, the request_id. A 401 for a missing or invalid API key and the 429s of the per-minute limit and of a used-up quota come from our gateway: they have the X-Request-Id header but no request_id in the body. Validation errors also carry an errors object that names each parameter. Where waiting helps, a Retry-After header says how many seconds to wait. An unexpected 500 carries no code, only the request_id, and so does the 503 "This request is still being rendered" (Retry-After: 1). The info line links a page that explains the error and what to do about it: the page of the browser's network error when a website could not be loaded (for example ERR_CONNECTION_REFUSED), otherwise the page of the error.code (for example invalid_parameters). All of them are listed under errors.
{
"message": "The target website could not be loaded (ERR_CONNECTION_REFUSED).",
"error": {
"code": "target_unreachable",
"message": "The target website could not be loaded (ERR_CONNECTION_REFUSED)."
},
"actions": {
"docs": "https://screenshotbase.com/docs/openapi.yaml"
},
"info": "For more information, see documentation: https://screenshotbase.com/errors/err-connection-refused/",
"request_id": "3f1c9a52-6d0e-4b7a-9c1e-2b8f5d4a7e10"
}
Status codes
Here is a list of the different categories of status codes returned by the screenshotbase.com API. Use these to understand if a request was successful.
- Name
200- Type
- Description
A 200 status code indicates a successful response: the page was captured as the target answered it, whatever its HTTP status. A 404 or 500 page of the target, a login wall, or a bot challenge page is captured and billed like any other page, as is the error page the browser shows for it. The response says what the target answered:
X-Target-Statusis the HTTP status of its page, andX-Blocked-Bynames who served a bot challenge or block page (for examplecloudflare); withignore_host_errors=0such pages fail with a424instead (see below).
- Name
202- Type
- Description
A 202 status code answers a request with
async=true: the body is the job, which is rendered in the background (see Async Jobs & Webhooks).
- Name
400- Type
- Description
A 400 status code indicates that the hostname of the target website could not be resolved (DNS failure), error code
target_unresolvable. Check that the URL you passed actually exists. APOSTwhose body the API cannot read also answers 400, error codeinvalid_parameters: JSON that does not parse or is not an object, JSON sent as a form (curl -dwithout the headerContent-Type: application/json), or a body that is neither JSON nor a form (such astext/plain). Requests answered with 400 are not billed.
- Name
401- Type
- Description
A 401 status code indicates that your API key is missing or invalid. A missing key returns the message
No API key found in request(error codemissing_api_key); an invalid key returnsUnauthorized(error codeinvalid_api_key).
- Name
403- Type
- Description
A 403 status code indicates that your request was refused: the API key belongs to a different everapi product (error code
key_not_allowed_for_product), the request came from a referrer that is not on your API key's whitelist (error codereferrer_not_allowed), orip_country_codewas sent without a plan that includes it (error codeplan_upgrade_required). Every paid plan includesip_country_code; a free account can make 5 renders with it in any 5 days, and the message names when the next one is available. An async job requested with a key that belongs to no screenshotbase account answers 403 with the error codeforbidden. Requests answered with 403 are not billed.
- Name
404- Type
- Description
A 404 status code indicates that a requested endpoint does not exist, or that an async job does not exist, belongs to another account, was deleted, or its result is no longer kept (error code
not_found).
- Name
405- Type
- Description
A 405 status code (error code
method_not_allowed) indicates an HTTP method the endpoint does not support, and theAllowheader names those it does:/v1/takeacceptsGET, andPOSTwith a JSON body. AHEADrequest to/v1/takeanswers 405 without rendering anything and is not billed.
- Name
408- Type
- Description
A 408 status code (error code
target_timeout) indicates that the target website took too long to load within the configuredtimeout, or that the render did not finish in its time limit: 110 seconds from the start of the request for every render, a screenshot, a PDF, markdown including its conversion, or a render of HTML input, whatever thetimeout(see PDF time limit). A tool call of the MCP server has about 12 seconds. A less strictwait_untilvalue, such asdomcontentloaded, or a shorterdelayoften helps; a page that needs longer can be rendered as an async job, with up to 300 seconds. A render that runs out of time during itsactionsnames the step (... during actions.3 (wait_for_selector)). Requests answered with 408 are not billed, unless anevaluatestep or thescriptsran before, or a wait of yours ran out (wait_for_selector, or a step ofactions): those count like the failure conditions, the first 25 a day free, then billed 1.
- Name
409- Type
- Description
A 409 status code answers the result of an async job that is not completed (error code
job_not_completed), or a request whoseIdempotency-Keyis still being answered for an earlier request (error codeidempotency_key_in_use,Retry-After: 1).
- Name
422- Type
- Description
A validation error has occurred (error code
invalid_parameters). Parameter validation failures return a JSON response with anerrorsobject describing which parameter failed and why, for exampleThe delay field must not be greater than 30., aqualityoutside 0 to 100, a viewport outside its bounds, more than 50hide_selectors,webhook_urlwithoutasync=true, or anIdempotency-Keysent again with a different request.An image larger than its format holds (a WebP taller than 16,383 px, say) answers with the error code
output_too_large_for_formatand a message that names the limit;format=pngor a smaller page or viewport works (see size limits).A target URL that answers with a file instead of a web page, a PDF (
Content-Type: application/pdf) or a download (Content-Disposition: attachment, or a type the browser does not display, such asapplication/zip), answers with the error codetarget_not_renderableand a message that names the type, for exampleThe target URL answered with a file (application/pdf), not a web page, so it cannot be rendered., as soon as the target's answer arrives.Markdown output of a page that rendered without any text or image to convert (an empty page, or content only in iframes or shadow DOM) answers with the error code
empty_content; the same request withformat=pngshows what the browser got.URL-safety rejections carry the error code
target_blocked_private_rangeand amessageinstead of anerrorsobject:URLs targeting localhost are not allowed.,URLs targeting private or reserved IP ranges are not allowed.orURLs targeting internal host names are not allowed.(a URL that is not http or https,Only http and https URLs are allowed., a URL on port 0 or on a port browsers block, such as 22 or 25,URLs on port 0 or on a port browsers block (such as 22 or 25) are not allowed., and aurlover 8,192 characters,The url must not be longer than 8192 characters., areinvalid_parameters). The API refuses URLs whose host is, or resolves to, a loopback, private, link-local (including cloud metadata), carrier-grade NAT or other reserved IPv4 or IPv6 address, and internal host names such as localhost,*.local,*.internalor single-label names. The same rules apply to every redirect and every resource the page loads: such resources are not fetched, and if the page itself redirects to such an address, the request fails with this status.With
ip_country_code, the error codegeo_target_refusedmeans that the proxy network we load pages through for that country will not load this website (its policy for the site); another country, or the same request withoutip_country_code, may work. Such a render does not count towards the free account's renders withip_country_code.The failure conditions of a request answer 422 too:
selector_not_foundwhen no element matchesselectorwithin 5 seconds anderror_on_selector_not_found=1, andcontent_condition_failedwhen the page shows a text offail_if_content_containsor lacks one offail_if_content_missing. A step ofactions, or thescripts, that cannot do what it says answersaction_failed, naming the step by its index and type (The step actions.2 (click) failed: ...); mark a stepoptionalto go on without it. They tell you something about the page, so the first 25 such failures a day per account are free and each one after that is billed like a render. Once anevaluatestep or thescriptsran, any failure of that render (whatever its status, but a500, a failure of our own proxies andgeo_proxy_unavailable) is billed one request, since that code could read the page.With
proxy, the error codeproxy_not_allowedmeans that your proxy is on a private, reserved or internal network (or resolves to one), which renders never connect to.For a PDF,
The pdf_page_ranges select no page of the rendered document.means that none of the pages inpdf_page_rangesexists in the printed document. For markdown,The page is too large to convert to markdown.(error codepage_too_large) means that the page has too much HTML, or its conversion needs too much memory; withformat=htmlthe same code means that the page's HTML is larger than 20 MiB. Withmax_file_size, the error codemax_file_size_unreachablemeans that no encoding of the image fits, not even at the lowest quality, with the fewest colors and at a quarter of its size: raisemax_file_size, or ask for a smaller image or another format. For HTML and markdown input (POST /v1/take), theerrorsobject can saySend only one of url, html and markdown.,Either the url, the html or the markdown field is required.,The html field must not be larger than 10 MB (10485760 bytes); with async=true up to 50 MB.,The markdown field must not be larger than 1 MB (1048576 bytes).,The markdown field must be UTF-8 text.,The markdown field could not be converted to HTML: ...orThe html field is only accepted in the JSON body of a POST request.(also onGET, and the same formarkdown). Requests answered with 422 are not billed, except the failure conditions past their daily allowance.
- Name
424- Type
- Description
A 424 status code (error code
target_unreachable) indicates that the target website could not be loaded: the render depends on it, and it failed. The message includes the underlying network error, e.g.The target website could not be loaded (ERR_CONNECTION_FAILED).; a connection that could not be established at all is reported asERR_CONNECTION_FAILED.With
proxy, the error codeproxy_errormeans that your proxy could not be used (it could not be reached, refused the credentials or did not answer as a proxy) or could not connect to the website; theinfolink names the network error.With
fail_if_request_failed, the error coderequest_failedmeans that a request of the page whose URL matches one of its patterns failed, with a network error (named in the message) or an HTTP status of 400 or more. Like the other failure conditions, the first 25 a day per account are free and each one after that is billed like a render.With
ignore_host_errors=0, a target that answers a bot challenge or block page fails with the error codetarget_blocked(the body'sblocked_bynames who served it, asX-Blocked-Bydoes), and one that answers an HTTP status of 400 or more withtarget_http_error(the body'starget_status), instead of a capture of that page. Requests answered with 424 are not billed, exceptrequest_failedpast the daily allowance of failure conditions.These failures were answered with
502until October 2026; theerror.codevalues are the same. A502never reached a client with its body: Cloudflare, in front of the API, replaces every502and504body with its own page.
- Name
429- Type
- Description
A 429 status code indicates that you have hit a limit of your plan; it is not billed. For more please upgrade your plan.
quota_exceeded: your monthly quota is used up. Every request of your quota can be used: the request that uses the last one is answered, the next one gets this status. On the request that first finds the quota used up,Retry-Afteris the number of seconds until the quota resets (quota.resets_at); after that our gateway answers every request with this429withoutRetry-After, so readquota.resets_atin the body. A PDF, markdown, and any render of HTML input, is checked against your quota before the page is rendered: if the quota does not cover it, the response carriesquota.required, the number of requests the call would have cost.grace_quota_exceeded: the grace quota of an unpaid invoice is used up; it lasts until the invoice is paid, so there is noRetry-After.rate_limit_exceeded: the free plan's limit of requests per minute (see rate limit);Retry-Afteris the time until the next full minute.concurrency_limit_exceeded: every render your plan may run at the same time is running (see concurrency);Retry-After: 1. Send the request again when one of your renders is done. An account may also have its concurrency times 10 async jobs queued or rendering at once; past that the create answers this code withoutRetry-After: send it again when one of your jobs is done.
- Name
500- Type
- Description
A 500 status code indicates an internal server error: the page could not be rendered for a reason not listed here. Such requests are not billed. Let us know at support@screenshotbase.com, with the
request_idof the response. For HTML input, the error code isrender_failedand the messageThe page could not be rendered.; other unexpected errors have no code.
- Name
502- Type
- Description
A 502 status code comes from a gateway in front of the API, never from a render: Cloudflare's own HTML error page when it could not get an answer from our servers in time, for example while they restart. It has no JSON body and no
error.code; send the request again after a few seconds. A website that could not be loaded answers424(see above).
- Name
503- Type
- Description
A 503 status code indicates that a result requested with
upload=1was rendered but could not be stored (error codestorage_unavailable,The file could not be stored. Please try again.), or that every render slot of our servers is taken, or your account already runs 8 renders on that server (error coderenderer_busy). Both carryRetry-After: 5; the request is not billed, send it again after that. Withip_country_code, the error codegeo_proxy_unavailable(Retry-After: 5) means that the proxy network has no capacity for that country right now: send the request again later, or try another country; it is not billed and does not count towards the free account's renders withip_country_code. A 503 withRetry-After: 1and the messageThis request is still being renderedmeans that an earlier attempt of the same request, with the sameX-Request-Id, is still rendering. This response is not billed, but the earlier attempt is billed when it finishes, although its result does not reach you. A request you send again is a new render and is billed separately.
- Name
504- Type
- Description
A 504 status code indicates that our gateway stopped waiting for the render before it finished. It can be Cloudflare's own HTML error page, without a JSON body or
error.code. The render may still finish and be billed, although its result does not reach you; a request you send again is a new render and is billed separately. To avoid it, make the render faster: a shorterdelay, a smaller page, or a less strictwait_until.