How to handle API errors

Error handling is an essential part of any high-quality application. Make sure you handle all errors returned by the ScreenshotOne API correctly and provide informative explanations to your customers or react to them accordingly.

Following HTTP standards

The ScreenshotOne API is on-purpose built using HTTP protocol and follows HTTP standards as much as possible. To make sure the API will be stable and can support customers for years to come.

In general, if the resulting status code is in the range of 400-599, then we are dealing with errors.

1
GET https://api.screenshotone.com/?[options]
2

3
Content-Type: application/json
4

5
{
6
    "is_successful":false,
7
    "error_code": "an_error_code",
8
    "error_message": "An error message"
9
}

Errors caused by API consumers

All errors caused by invalid requests, absent credentials, or any reasons caused by you, an API consumer, are marked with status codes 400-499. It means, that until you find a way to fix them, the request won’t be executed successfully.

API internal errors

Errors with status codes in the range 500-599 are caused by the API internal reasons and you have almost little influence over that.

But you can safely retry them. Except in a few cases. When you get a network error (network_error), it might be because the site blocks the API, and there is no sense in retrying the request. Or if the site returned an error (host_returned_error) and it is an error within the range 400-499, it means that the API is either blocked, or you need to change the request to the site.

Showing errors to your end users

In general, you can try to just return the error message provided by the API, but if you want to show a more user-friendly message, you can use the following code:

1
const response = await fetch("https://api.screenshotone.com/...");
2

3
// after retries and other processing, once you decide to show an error to your end user
4
if (!response.ok) {
5
    const errorData = await response.json();
6

7
    const errorMessage = generateUserFriendlyErrorMessage(errorData);
8

9
    // show the error to your end user in your UI, CLI or any other way
10
    showErrorToUser(errorMessage);
11
}
12

13
function generateUserFriendlyErrorMessage(error) {
14
    // these are error messages for your public users, not for you
15
    switch (error.error_code) {
16
        case "screenshots_limit_reached":
17
            return "The screenshot rendering is not available. Please, retry later.";
18
        case "concurrency_limit_reached":
19
        case "temporary_unavailable":
20
            return "Please try again in a moment.";
21
        case "request_not_valid":
22
            return "Please, make sure your request is valid and try again.";
23
        case "selector_not_found":
24
            return "The target element was not found on the page";
25
        case "name_not_resolved":
26
            return "Unable to resolve the domain name. Check that there is no typo in the URL. If this is a new site, please wait for DNS propagation.";
27
        case "network_error":
28
            return "Unable to connect to the requested URL. The site may be blocking access or temporarily down.";
29
        case "host_returned_error":
30
            if ([401, 403, 429].includes(error.returned_status_code)) {
31
                return "The target website blocks automated screenshot rendering.";
32
            }
33
            if (error.returned_status_code >= 500) {
34
                return "The target website is temporarily down. Please, retry later.";
35
            }
36
            if (error.returned_status_code == 404) {
37
                return "The target website returned a 404 HTTP error—the page not found.";
38
            }
39

40
            return `The target website returned a ${error.returned_status_code} HTTP error.`;
41
        case "timeout_error":
42
            return "The screenshot rendering timed out. Please, try again.";
43
        case "storage_returned_transient_error":
44
        case "internal_application_error":
45
        case "request_aborted":
46
            return "Failed to render the screenshot. Please try your request again";
47
        case "access_key_required":
48
        case "access_key_invalid":
49
        case "signature_is_required":
50
        case "signature_is_not_valid":
51
        case "invalid_storage_configuration":
52
        case "script_triggers_redirect":
53
        case "storage_access_denied":
54
        case "content_contains_specified_string":
55
        case "invalid_cookie_parameter":
56
        case "resulting_image_too_large":
57
            // these are errors that often are not caused by the end user action,
58
            // and they need to be fixed on your or our side
59
            return "The screenshot rendering failed. Please, reach out to support.";
60
        default:
61
            // return a generic error message
62
            // or the message provided by the API error.error_message
63
            return "The screenshot rendering failed. Please, reach out to support.";
64
    }
65
}

These are the most common errors often caused by end users. If you want to process more codes, check out all our errors.

When to retry with a proxy

Do not send every request through a residential or premium proxy by default. Proxies are slower, more expensive, and introduce another service that can fail. The practical strategy is:

Try the request without a proxy.
If the response suggests an IP reputation, location, rate-limit, or routing issue, retry the same request once with a proxy.
If the proxied request also fails, inspect the error instead of looping forever.

Use proxies only for pages you own, pages you are authorized to test, or pages where automated access is allowed. Do not use proxy retries to access content you are not allowed to access, evade account restrictions, bypass paywalls, ignore robots or site terms, or work around a clear “no automated access” decision by the target website.

Error or signal	Retry without a proxy?	Retry with a proxy?	Notes
`temporary_unavailable`	Yes, with backoff	No, not first	This is usually ScreenshotOne-side load or a transient internal issue. A proxy does not help.
`internal_application_error`	Yes, with backoff	No, not first	Retry the same request. If it repeats, contact support.
`concurrency_limit_reached`	Yes, after `concurrency.reset`	No	Use the usage endpoint and queue requests. A proxy does not change your ScreenshotOne request limit.
`storage_returned_transient_error`	Yes, with backoff	No	The target page rendered, but your storage returned a transient error.
`request_aborted`	Yes, after checking client/serverless timeouts	Usually no	Increase your HTTP client timeout first. Retry with a proxy only if the abort happens while using your own proxy and you are testing a different proxy endpoint.
`network_error`	Sometimes	Yes, if permitted and repeated	Useful when the target blocks ScreenshotOne IPs, has regional routing issues, or your chosen proxy has access to the target host.
`timeout_error`	Sometimes	Sometimes	First reduce page weight, adjust `timeout` or `navigation_timeout`, or use async requests. Try a proxy if the timeout looks like IP-based throttling or blocking.
`host_returned_error` with `returned_status_code=403`	Usually no	Sometimes	Retry with a proxy only when you are allowed to access the page and the 403 looks like IP/location reputation. If it is an authentication or permission error, fix authentication or stop.
`host_returned_error` with `returned_status_code=429`	Yes, after waiting	Sometimes	Respect rate limits. A proxy may help only when you are allowed to retry and the target expects traffic from a different approved route.
`host_returned_error` with `returned_status_code=502`, `503`, or `504`	Yes, with backoff	Sometimes	Retry normally first. A proxy can help when a CDN or edge route behaves differently by location or IP range.
`content_contains_specified_string`	No	Sometimes	Use this only when you intentionally configured `fail_if_content_contains` to detect a known block page or challenge page.
`content_missing_specified_string`	No	Sometimes	Use this only when you intentionally configured `fail_if_content_missing` to detect that expected content did not load.
`name_not_resolved`	After DNS changes, yes	Usually no	Fix the URL or wait for DNS propagation. A proxy is not the first fix for a bad or unavailable hostname.
`request_not_valid`, `access_key_invalid`, `signature_is_not_valid`, `selector_not_found`, `storage_access_denied`, `resulting_image_too_large`	No	No	Change the request, credentials, selector, storage configuration, or image options.

An example of retrying with a proxy only for selected errors:

1
const apiUrl = "https://api.screenshotone.com/take";
2
const accessKey = process.env.SCREENSHOTONE_ACCESS_KEY;
3
const proxyUrl = process.env.SCREENSHOT_PROXY_URL; // http://user:pass@host:port
4

5
if (!accessKey) {
6
    throw new Error("SCREENSHOTONE_ACCESS_KEY is required");
7
}
8

9
function shouldRetryWithProxy(error) {
10
    if (error.error_code === "network_error") {
11
        return true;
12
    }
13

14
    if (error.error_code === "timeout_error") {
15
        return true;
16
    }
17

18
    if (error.error_code === "host_returned_error") {
19
        const status = Number(error.returned_status_code);
20
        return [403, 429, 502, 503, 504].includes(status);
21
    }
22

23
    return [
24
        "content_contains_specified_string",
25
        "content_missing_specified_string",
26
    ].includes(error.error_code);
27
}
28

29
function buildScreenshotUrl(options) {
30
    const url = new URL(apiUrl);
31
    url.searchParams.set("access_key", accessKey);
32

33
    for (const [key, value] of Object.entries(options)) {
34
        if (Array.isArray(value)) {
35
            for (const item of value) {
36
                url.searchParams.append(key, item);
37
            }
38
        } else if (value !== undefined && value !== null) {
39
            url.searchParams.set(key, String(value));
40
        }
41
    }
42

43
    return url;
44
}
45

46
async function takeScreenshotWithOptionalProxy(options) {
47
    const response = await fetch(buildScreenshotUrl(options));
48

49
    if (response.ok) {
50
        return await response.arrayBuffer();
51
    }
52

53
    const error = await response.json();
54

55
    if (!proxyUrl || !shouldRetryWithProxy(error)) {
56
        throw new Error(error.error_message || "Screenshot rendering failed");
57
    }
58

59
    const retryOptions = {
60
        ...options,
61
        proxy: proxyUrl,
62
    };
63

64
    const proxyResponse = await fetch(buildScreenshotUrl(retryOptions));
65

66
    if (!proxyResponse.ok) {
67
        const proxyError = await proxyResponse.json();
68
        throw new Error(
69
            proxyError.error_message || "Screenshot rendering failed with proxy"
70
        );
71
    }
72

73
    return await proxyResponse.arrayBuffer();
74
}
75

76
const screenshot = await takeScreenshotWithOptionalProxy({
77
    url: "https://example.com",
78
    format: "png",
79
});

Reporting errors

All ScreenshotOne API errors are logged and we are acknowledged by them. And will react to them as fast as possible.

In general, you don’t need to report to us any errors. But if it blocks your work or you want us to prioritize fixing them, please, feel free to report an error at support@screenshotone.com.

Error reference

All API errors are listed in the error reference.