Error codes

Every failed RenderScreenshot request returns a non-2xx HTTP status and a JSON body with one error object. This page is the index: it lists each code, its status and whether a retry can help, and links to a page per code. It is part of the API documentation. For symptoms that are not errors, such as a blank image, see troubleshooting.

The error object

{
  "error": {
    "type": "validation_error",
    "code": "invalid_url",
    "message": "The URL 'not-a-url' is not a valid HTTP(S) URL",
    "param": "url",
    "retryable": false,
    "docs": "https://renderscreenshot.com/docs/errors/invalid-url"
  },
  "request_id": "3f1c9a52-7d4e-4b8a-9e21-6c0d5b7a8f13"
}

A failed request does not use a credit.

Status codes at a glance

Code index

Validation (400)

The API also returns parameter-specific validation codes. Each one sets error.param, so you can show the message next to the right field:

• Request options: invalid_device, invalid_cache_ttl, invalid_media_type, invalid_timezone, invalid_locale, invalid_geolocation.
• Target authentication and cookies: invalid_auth_type, missing_auth_credentials, missing_auth_token, invalid_cookie, invalid_same_site.
• PDF: invalid_paper_format, invalid_pdf_scale, invalid_page_ranges, invalid_pdf_dimension, invalid_pdf_margin.
• Batch and cache endpoints: missing_urls, batch_size_exceeded, missing_cache_key, invalid_date.

Authentication (401)

Authorization (403)

Target page (422)

All of these return HTTP 422. blocked and console_error have retryable: false; the others have retryable: true. Match on error.code; error.message carries the browser's detail, for example blocked_url: host localhost is blocked.

Rate limits (429) and server errors (500)

Retry code for the SDKs

Base the decision on the HTTP status. It is the one field every SDK exposes the same way. Each listing reads the key from RS_API_KEY and lets non-retryable errors through. Tested on 2026-10-15 with renderscreenshot 1.1.0 for Node 22.18, the Python SDK 1.0.0 on Python 3.14 and the Ruby gem 1.0.0 on Ruby 4.0, against a local stub that replays the API's error bodies for 400, 422, 429 and 500.

Node.js

import { Client, TakeOptions, RenderScreenshotError } from 'renderscreenshot';
import { writeFile } from 'node:fs/promises';

const client = new Client(process.env.RS_API_KEY);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// 429 and 5xx can succeed on a later attempt. 400, 401 and 403 cannot.
const isTransient = (status) => status === 429 || status >= 500;

async function takeWithRetry(options, attempts = 3) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await client.take(options);
    } catch (err) {
      const transient = err instanceof RenderScreenshotError && isTransient(err.httpStatus);
      if (!transient || attempt === attempts) throw err;
      await sleep((err.retryAfter ?? 2 ** attempt) * 1000);
    }
  }
}

const image = await takeWithRetry(TakeOptions.url('https://example.com').preset('og_card'));
await writeFile('screenshot.png', image);

Python

import os
import time

from renderscreenshot import Client, RenderScreenshotError, TakeOptions

client = Client(os.environ['RS_API_KEY'])


def take_with_retry(options, attempts=3):
    for attempt in range(1, attempts + 1):
        try:
            return client.take(options)
        except RenderScreenshotError as e:
            # 429 and 5xx can succeed on a later attempt. 400, 401 and 403 cannot.
            transient = e.http_status == 429 or e.http_status >= 500
            if not transient or attempt == attempts:
                raise
            time.sleep(e.retry_after or 2 ** attempt)


image = take_with_retry(TakeOptions.url('https://example.com').preset('og_card'))
with open('screenshot.png', 'wb') as f:
    f.write(image)

Ruby

require 'renderscreenshot'

client = RenderScreenshot.client(ENV.fetch('RS_API_KEY'))
options = RenderScreenshot::TakeOptions.url('https://example.com').preset('og_card')

attempts = 0
begin
  attempts += 1
  image = client.take(options)
rescue RenderScreenshot::RateLimitError, RenderScreenshot::ServerError => e
  raise if attempts >= 3
  sleep(e.retry_after || 2**attempts)
  retry
rescue RenderScreenshot::Error => e
  # A 422 render failure may pass on a second try, unless the URL was refused.
  raise if e.http_status != 422 || e.message.start_with?('blocked_url:') || attempts >= 2
  retry
end

File.binwrite('screenshot.png', image)

The Ruby listing also retries a 422 once, because it can read the refusal prefix in e.message. In the stub test it made one extra request for a page that failed once, and none for http://localhost. For queues, idempotency and backoff with jitter, read error handling and retries.

See also

• Troubleshooting: blank images, cookie banners, login walls
• Rate limits: limits per plan and the X-RateLimit-* headers
• Signed URLs: fixing invalid_signature and expired_signature
• SDKs: error classes in all official SDKs

Last verified 2026-10-15 against the API source.