Errors
Docs · OG · PDF · Screenshot · Signed URLs · Errors · Limits
Every error is JSON with a code, a message and a docs link. The message names the limit and its value. The docs link brings you to the code below.
invalid_request HTTP 400
When: A field is missing, has the wrong type or is outside its range, or a signed URL repeats a query key.
What to do: Read the message: it names the field and the allowed range. Fix the request and send it again.
unauthorized HTTP 401
When: The Authorization header is missing, the key is unknown or revoked, or the account is suspended.
What to do: Send Authorization: Bearer sh_live_... with the current key from your dashboard. If you rotated the key, the old one is dead.
quota_exceeded HTTP 402
When: You used all the renders in your plan for this UTC month.
What to do: Wait for the reset date in the message (the X-Render-Quota-Reset header has it too) or change plan on your dashboard. We never charge more or upgrade you on our own.
bad_signature HTTP 403
When: A signed OG URL has a wrong or missing signature, or its exp time has passed.
What to do: Sign the URL again with your current signing secret. Rotating the secret invalidates old signed URLs.
payload_too_large HTTP 413
When: The request body is over 1 MB, or a field is over its size cap (for example OG html over 256 KB).
What to do: Send less. The message names the field, the cap and your size.
forbidden_target HTTP 422
When: The URL uses a scheme or port we do not allow, is an IP address, resolves to a private address, or is a domain whose owner asked us to stop.
What to do: Use an http or https hostname on port 80, 443, 8080 or 8443 that points to a public server. See the bot page for opt-outs.
output_too_large HTTP 422
When: The result would be over its cap: 32 Mpx (32,000,000 pixels) or 10 MB for an image, 20 MB or 200 pages for a PDF.
What to do: Ask for less: a smaller viewport, a lower device_scale_factor, a shorter page, fewer pages, or a lower quality.
rate_limited HTTP 429
When: Too many renders a minute for your plan, too many cache hits a minute, or more renders in flight than your plan allows.
What to do: Wait for the number of seconds in the Retry-After header and try again. Limits per plan are on the limits page.
busy HTTP 429
When: All render slots and all waiting places are taken, or yours did not start within 10 seconds. Every plan shares the same queue.
What to do: Retry after the number of seconds in Retry-After. Use a client timeout of 35 seconds.
target_unreachable HTTP 502
When: We could not reach the page you asked for: DNS failed, or the connection or TLS handshake failed.
What to do: Check the URL is public and the certificate is valid, then retry.
render_timeout HTTP 504
When: The render did not finish within 20 seconds.
What to do: Use wait_until=domcontentloaded, a simpler page, or no delay_ms. Timeouts are not counted against your allowance.
internal HTTP 500
When: Something went wrong on our side.
What to do: Retry once. If it repeats, send us the X-Render-Id header from the response. It is not counted against your allowance.