Skip to content
Getting StartedGuidesBlogChangelogCustomersPricing

Matched Failed Request

This API error is returned when a resource URL matches a pattern in the fail_if_request_failed option and either:

  • the request fails at the browser or network level; or
  • the resource returns an HTTP status code from 400 through 599.

Requests that fail with the browser’s net::ERR_BLOCKED_BY_CLIENT error, including suffixed forms such as net::ERR_BLOCKED_BY_CLIENT.Inspector, do not trigger this error, regardless of the blocking source. For example, a cookie banner’s CSS blocked by block_cookie_banners=true is ignored even when you use fail_if_request_failed=*.css*.

This code can come from ScreenshotOne’s resource blockers, certain browser security checks, referrer-policy enforcement, or DevTools/automation interception. It does not reliably identify who blocked the request or indicate an origin failure. These errors are excluded to avoid treating deliberately blocked resources as failed assets. Other browser or network failures and HTTP 4xx/5xx responses still count.

{
    "is_successful": false,
    "error_code": "matched_failed_request",
    "error_message": "A request matched by the specified pattern by the `fail_if_request_failed` option has been failed. If it seems to be a mistake or not what you expected, please, reach out to `support@screenshotone.com` as quickly as possible, and we will assist and try to resolve your problem.",
    "documentation_url": "https://screenshotone.com/docs/errors/matched-failed-request/"
}

Reasons and how to fix

Section titled “Reasons and how to fix”

You get this error because you specified the fail_if_request_failed option and a matching resource failed. This can indicate a temporarily unavailable asset, a cache or CDN inconsistency, or a persistent problem on the target website.

ScreenshotOne does not retry the API request automatically. If a temporary asset failure is acceptable in your use case, retry the same API request in your integration. If the matching resource still fails after your retry limit, treat the website as persistently broken.

If you do not want a failed resource to fail the rendering request, remove the parameter. For example, change:

https://api.screenshotone.com/take?access_key=<your access key>&url=https://example.com&fail_if_request_failed=*example.com*

Make it like this:

https://api.screenshotone.com/take?access_key=<your access key>&url=https://example.com

Use narrow wildcard patterns for resources that are essential to a valid screenshot. Broad patterns can also match optional or third-party resources that fail to load.

Ignoring client-side blocks does not guarantee that all required styles are present. If a blocker removes essential CSS, disable the relevant blocking option or adjust your custom blocking patterns. Blocking the main page itself can still cause a navigation error.

Reach out to support

Section titled “Reach out to support”

If your use case requires detecting ERR_BLOCKED_BY_CLIENT errors too, or you need help, email support@screenshotone.com or use the support chat on our website.