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.

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

Content-Type: application/json

{
    "is_successful":false,
    "error_code": "an_error_code",
    "error_message": "An error message"
}

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.

You still might want to try to retry errors like network_error and host_returned_error (if the host’s error is 403 in the returned_status_code property of the response), but try to add a residential rotating proxy to that API request. Maybe the second time you can succeed and the request will work for you.

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.