blocked

A blocked request is one where the target page could not be captured because access was stopped on purpose, either by RenderScreenshot or by the site itself. Unlike a timeout, the same request fails the same way every time, so a retry does not help. This page is part of the error code reference.

Example response

When RenderScreenshot refuses the target, the response looks like this today:

{
  "error": {
    "type": "target_error",
    "code": "screenshot_failed",
    "message": "blocked_url: host localhost is blocked",
    "retryable": true
  },
  "request_id": "req_9f8e7d6c5b4a3210"
}

The retryable flag is true for every render failure. For a blocked_url: message, ignore it: the next attempt is refused too.

Cause 1: RenderScreenshot refused the URL

The browser runs in RenderScreenshot's cloud, not on your network. To keep it from reaching private systems, every target is checked before the page loads, and again for every address the page connects to while it loads. The text after blocked_url: names the rule:

Fixes:

1. Local development. Put the page behind a public URL: a preview deployment, a staging host or a tunnel with a public HTTPS address.
2. Internal dashboards and reports. Render the HTML yourself and send it in the html parameter. The renderer never fetches your network. See content input.
3. A non-standard port. Serve the page on 443 behind a reverse proxy.
4. Basic auth in the URL. Remove the credentials from the URL and send them in network.auth. See authenticated pages.
5. A private asset on a public page, such as an image from an internal CDN. Serve that asset publicly, or block its URL pattern with block.requests so the rest of the page can render.

Cause 2: The site blocked the renderer

Bot protection, a web application firewall or a geo-block can stop a headless browser. In that case the page usually still loads, so you get HTTP 200 and an image of a challenge or "access denied" page rather than an error. The API specification reserves the code blocked for this case.

Fixes:

1. If you own the site, allow the renderer in your firewall or bot-management rules.
2. If you do not, check whether the site allows automated access before you go further.
3. If the site owner gives you a bypass header or cookie for automated visits, send it with network.headers or network.cookies in a POST request.

The bot protection and CAPTCHA guide covers this case in depth.

Handle it in code

Both listings below stop on a refusal instead of retrying, and keep the request ID for support. Tested on 2026-10-15 with Node 22.18 and with the Ruby gem 1.0.0 on Ruby 4.0, against a local stub that returns the response above.

Node.js

const target = 'http://localhost:3000/dashboard';

const res = await fetch('https://api.renderscreenshot.com/v1/screenshot', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: target, preset: 'og_card' }),
});

if (!res.ok) {
  const { error, request_id: requestId } = await res.json();
  const refused = error.code === 'blocked' || error.message.startsWith('blocked_url:');
  if (res.status === 422 && refused) {
    // Permanent for this URL: do not retry, change the target instead.
    console.error(`Refused ${target}: ${error.message} (request ${requestId})`);
    process.exit(2);
  }
  throw new Error(`${res.status} ${error.code}: ${error.message}`);
}

Ruby

require 'renderscreenshot'

client = RenderScreenshot.client(ENV.fetch('RS_API_KEY'))
options = RenderScreenshot::TakeOptions.url('http://localhost:3000/dashboard').preset('og_card')

begin
  image = client.take(options)
  File.binwrite('screenshot.png', image)
rescue RenderScreenshot::Error => e
  refused = e.code == 'blocked' || e.message.start_with?('blocked_url:')
  raise unless e.http_status == 422 && refused

  # Permanent for this URL: do not retry, change the target instead.
  warn "Refused: #{e.message} (request #{e.request_id})"
  exit 2
end

Both listings accept either the blocked code or the blocked_url: prefix, so they keep working when the dedicated code arrives.

Last verified 2026-10-15 against the renderer's URL checks.