Caching & idempotency

The API evaluates requests in this order: idempotency replay → cache lookup → fresh Render. Understanding both mechanisms helps you avoid duplicate work and unnecessary Quota consumption.

Render cache

Identical requests from the same Account can be served from cache. A cache key is computed from the target url and pixel-affecting options (format, quality, viewport, dpr, full_page, block_ads, wait_until, wait_for, delay).

These fields are excluded from the cache hash — changing them does not create a separate cache entry for the same pixels:

• response_type — the same Render can be returned as raw bytes or rebuilt as JSON
• cache_ttl — controls how long the entry lives, not what was rendered

Default TTL

cache_ttl defaults to 300 seconds (5 minutes). Set it per request:

Cache hit behavior

On a cache hit:

• Response is immediate (no Browserless round-trip)
• X-Render-Cached: true
• X-Render-Billable: false — does not consume monthly Quota
• JSON responses include "cached": true and "billable": false

Idempotency

Send an Idempotency-Key header (any opaque string, typically a UUID) to safely retry POST requests without creating duplicate Renders:

Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7

Rules

1. Same key + same body → replay the stored response. No new Render, no Quota charge.
2. Same key + different body → 422 idempotency_key_reused.
3. Replays set X-Idempotent-Replay: true, X-Render-Billable: false, and "billable": false in JSON bodies.

Idempotency entries expire after 24 hours.

Ordering with cache

If a request with an idempotency key matches a cache entry, the cached response is returned and stored under the idempotency key for future replays.

What is Billable?

Per-minute rate-limit slots are never refunded — a throttled or failed request still consumed its minute-window slot.

See Rate limits & quotas for Plan caps and Storage for JSON URL behavior on cached responses.