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.

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-Status is the HTTP status of its page, and X-Blocked-By names who served a bot challenge or block page (for example cloudflare); with ignore_host_errors=0 such pages fail with a 424 instead (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. A POST whose body the API cannot read also answers 400, error code invalid_parameters: JSON that does not parse or is not an object, JSON sent as a form (curl -d without the header Content-Type: application/json), or a body that is neither JSON nor a form (such as text/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 code missing_api_key); an invalid key returns Unauthorized (error code invalid_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 code referrer_not_allowed), or ip_country_code was sent without a plan that includes it (error code plan_upgrade_required). Every paid plan includes ip_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 code forbidden. 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 the Allow header names those it does: /v1/take accepts GET, and POST with a JSON body. A HEAD request to /v1/take answers 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 configured timeout, 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 the timeout (see PDF time limit). A tool call of the MCP server has about 12 seconds. A less strict wait_until value, such as domcontentloaded, or a shorter delay often 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 its actions names the step (... during actions.3 (wait_for_selector)). Requests answered with 408 are not billed, unless an evaluate step or the scripts ran before, or a wait of yours ran out (wait_for_selector, or a step of actions): 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 whose Idempotency-Key is still being answered for an earlier request (error code idempotency_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 an errors object describing which parameter failed and why, for example The delay field must not be greater than 30., a quality outside 0 to 100, a viewport outside its bounds, more than 50 hide_selectors, webhook_url without async=true, or an Idempotency-Key sent 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_format and a message that names the limit; format=png or 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 as application/zip), answers with the error code target_not_renderable and a message that names the type, for example The 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 with format=png shows what the browser got.

    URL-safety rejections carry the error code target_blocked_private_range and a message instead of an errors object: URLs targeting localhost are not allowed., URLs targeting private or reserved IP ranges are not allowed. or URLs 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 a url over 8,192 characters, The url must not be longer than 8192 characters., are invalid_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, *.internal or 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 code geo_target_refused means 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 without ip_country_code, may work. Such a render does not count towards the free account's renders with ip_country_code.

    The failure conditions of a request answer 422 too: selector_not_found when no element matches selector within 5 seconds and error_on_selector_not_found=1, and content_condition_failed when the page shows a text of fail_if_content_contains or lacks one of fail_if_content_missing. A step of actions, or the scripts, that cannot do what it says answers action_failed, naming the step by its index and type (The step actions.2 (click) failed: ...); mark a step optional to 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 an evaluate step or the scripts ran, any failure of that render (whatever its status, but a 500, a failure of our own proxies and geo_proxy_unavailable) is billed one request, since that code could read the page.

    With proxy, the error code proxy_not_allowed means 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 in pdf_page_ranges exists in the printed document. For markdown, The page is too large to convert to markdown. (error code page_too_large) means that the page has too much HTML, or its conversion needs too much memory; with format=html the same code means that the page's HTML is larger than 20 MiB. With max_file_size, the error code max_file_size_unreachable means that no encoding of the image fits, not even at the lowest quality, with the fewest colors and at a quarter of its size: raise max_file_size, or ask for a smaller image or another format. For HTML and markdown input (POST /v1/take), the errors object can say Send 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: ... or The html field is only accepted in the JSON body of a POST request. (also on GET, and the same for markdown). 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 as ERR_CONNECTION_FAILED.

    With proxy, the error code proxy_error means 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; the info link names the network error.

    With fail_if_request_failed, the error code request_failed means 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 code target_blocked (the body's blocked_by names who served it, as X-Blocked-By does), and one that answers an HTTP status of 400 or more with target_http_error (the body's target_status), instead of a capture of that page. Requests answered with 424 are not billed, except request_failed past the daily allowance of failure conditions.

    These failures were answered with 502 until October 2026; the error.code values are the same. A 502 never reached a client with its body: Cloudflare, in front of the API, replaces every 502 and 504 body 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-After is the number of seconds until the quota resets (quota.resets_at); after that our gateway answers every request with this 429 without Retry-After, so read quota.resets_at in 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 carries quota.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 no Retry-After.
    • rate_limit_exceeded: the free plan's limit of requests per minute (see rate limit); Retry-After is 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 without Retry-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_id of the response. For HTML input, the error code is render_failed and the message The 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 answers 424 (see above).

  • Name
    503
    Type
    Description

    A 503 status code indicates that a result requested with upload=1 was rendered but could not be stored (error code storage_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 code renderer_busy). Both carry Retry-After: 5; the request is not billed, send it again after that. With ip_country_code, the error code geo_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 with ip_country_code. A 503 with Retry-After: 1 and the message This request is still being rendered means that an earlier attempt of the same request, with the same X-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 shorter delay, a smaller page, or a less strict wait_until.