Errors

The reason the request was refused, as a short stable string. This is the field to branch on. Every code is listed under error codes below.

The same reason in words, written for a person to read. It can be reworded or made more specific at any time, so show it to a human rather than matching your code against it.

Sent only when a particular parameter is at fault. It is keyed by the query parameter, with the messages for that parameter, and it is left out entirely otherwise.

Identifies that one answer, and it is in our logs against the request that produced it. Quote it when you ask us about a failure and we can look up exactly what happened.

The rendered file. The body is the image or the PDF itself rather than JSON, so write it to a file instead of parsing it. The Content-Type names the format that was rendered.

The rendering is byte for byte the copy already held by the caller, named in the `If-None-Match` of the request, so no body is sent. What it costs depends on how that was established. An answer the cache could give is free: no credit, and counted against neither per-minute budget. One that had to render the page first, because the request sent `cache=0` or because the entry had lapsed, costs exactly what that render costs, a credit and a slot of the render budget, and what the caller saves is the download. `X-Cache: HIT` marks the free one; anything else was rendered, and carries the X-RateLimit headers to say so.

The request carried no bearer token, or a token that is unknown or revoked.

The account has no active plan, or it has used every credit in the current period. The code says which of the two it is.

The email address of the account has not been verified yet, or the token is not allowed to ask for the mode the request is in. The code says which of the two it is: a token carries a permission per mode, and one narrowed to screenshots cannot print a PDF.

A query parameter did not validate, or the target URL could not be reached or loaded ("The target URL could not be reached or loaded. Check that it is publicly available and try again."). The errors object names the parameter at fault. No credit is charged.

The account went over one of its two per-minute limits: the renders its plan allows, or the separate and far larger number of answers it may be served out of the cache. The X-RateLimit headers on this answer describe the limit that refused it. Wait for the number of seconds in the Retry-After header before sending the request again.

The render failed for a reason we did not recognise. The credit is refunded.

The rendering service failed to process the request. The credit is refunded and the request is worth sending again.

The rendering service was momentarily busy and stayed busy across our own retries. The credit is refunded. Unlike the 502 this is not a failure of anything: wait the few seconds in the Retry-After header and the same request goes through.

The render did not finish within its time budget. The credit is refunded and the request is worth sending again.

No bearer token was sent, or the token is unknown or revoked.

A signed URL did not verify. Either the signature does not match the query, or the token it names is unknown, revoked or expired. Rebuild the URL from the canonical form on the signed URLs page, and check that nothing was appended to it after it was signed.

A signed URL is past the `expires` moment it was signed with. The signature itself was fine, so sign a new URL with a later expiry.

The account exists but its email address has not been verified yet.

The token is not allowed to ask for this mode. A token carries a permission per mode, `screenshot` and `pdf`, and both are granted unless the token was deliberately narrowed. Widen it in your dashboard, or send the request with a token that holds the permission.

The account is on no plan, so it has no credits to spend. Pick a plan and the same request works.

Every credit in the current period is spent. It resets at the end of the period.

A query parameter is missing, malformed, or not accepted in the mode the request is in. The errors object names it.

The url is missing or is not a URL the API will accept. Fix the string and send it again.

The url points at a private, loopback or internal address. Reformatting it will not help; only a publicly reachable host is rendered.

The page itself could not be reached or loaded. Check that it is publicly available.

The account went over its renders per minute, or over the separate limit on the answers it may be served out of the cache. The X-RateLimit headers say which of the two. Wait for the Retry-After header and send the request again.

The render failed for a reason we did not recognise. The credit is refunded.

Something failed that we did not expect at all. The catch-all, and always worth reporting with the request id.

The rendering service failed to process the request. The credit is refunded and a retry is worthwhile.

The rendering service has spent its own capacity for the period. Nothing is broken, so back off for longer than you would on an ordinary upstream failure.

The rendering service was busy and stayed busy while we retried. Nothing is broken and nothing about the request is wrong; wait the seconds in Retry-After and send it again.

The render ran past its time budget. The credit is refunded and the same request may well succeed later.

No endpoint exists at that path.

The endpoint exists but does not accept that HTTP method. The Allow header names the ones it does.

The request went to the base URL the API used to be served on. Nothing about the request is wrong: send it to the base URL named in the message and the path after it, the parameters, the headers and the token all stay as they are.