Error codes
Every error has the same JSON shape, including on the endpoints that return an image or a PDF.
{
"status": "fail",
"code": "EFORBIDDENURL",
"message": "Destination is not allowed"
}
statusisfailwhen the request is at fault (4xx),errorwhen the server or the target is at fault (5xx).codeis stable: it is what your code should test.messageis in English, meant for humans, and may change.
Causes and fixes
| Code | HTTP | Likely cause | What to do |
|---|---|---|---|
EINVALIDPARAMS | HTTP400 | Likely causeA parameter is missing or has an invalid value. | What to doCompare the request with the reference; the message names the parameter. |
EINVALIDURL | HTTP400 | Likely causeThe url is malformed or is neither http nor https. | What to doSend an absolute address and encode it (encodeURIComponent). |
EUNAUTHORIZED | HTTP401 | Likely causeThe key sent in x-api-key is not known to the instance. | What to doFix the key, or remove the header for an anonymous call. |
EFORBIDDENURL | HTTP403 | Likely causeThe destination is private, local or internal, or its port is not allowed. | What to doOnly public pages can be read. For an intranet, host your own instance inside that network. |
EEMBEDNOTFOUND | HTTP404 | Likely causeThe path requested with embed does not exist for this page, or is null. | What to doCall /meta without embed to see the available fields; plan a fallback image. |
ESELECTORNOTFOUND | HTTP404 | Likely causeThe selector matches no visible element. | What to doCheck the selector in a browser; add waitForSelector if the element appears late. |
ENOTHTML | HTTP422 | Likely causeThe target is an image, a PDF or another file, not an HTML page. | What to doUse this endpoint on a page; /screenshot accepts other types. |
ETOOLARGE | HTTP422 | Likely causeThe PDF or the generated output exceeds the maximum size. | What to doMake the page smaller: turn printBackground off, or target a shorter page. |
ERATELIMIT | HTTP429 | Likely causeToo many requests in the current window. | What to doWait for the retry-after delay. Cache your results, or use a key. |
EBROWSER | HTTP500 | Likely causeChromium crashed or could not start. | What to doRetry. If the error persists on your instance, check the Chromium installation. |
EINTERNAL | HTTP500 | Likely causeUnexpected server error. | What to doRetry; if it happens again, open an issue with the x-request-id header of the response. |
EUNREACHABLE | HTTP502 | Likely causeThe target site does not answer: unknown name, refused connection, TLS error. | What to doCheck the address in a browser. The site may be down or blocking bots. |
ETARGETSTATUS | HTTP502 | Likely causeThe target site answered with an HTTP error (404, 403, 500…). | What to doThe message gives the status. Check that the page exists and is public. |
EBLOCKED | HTTP502 | Likely causeThe site served an anti-bot block page instead of its content. | What to doOmnillink does not work around these protections. Check the page in a browser, or ask the site for access. |
ECIRCUITOPEN | HTTP503 | Likely causeThe target site failed several times in a row; it is set aside for a few seconds. | What to doRetry after the delay given by the retry-after header. |
EROUTENOTFOUND | HTTP404 | Likely causeThe requested path does not exist in the API. | What to doCheck the path and version (/api/v1/…) in the reference. |
EBUSY | HTTP503 | Likely causeToo many renders are queued on the instance. | What to doRetry after a few seconds, with an increasing delay. |
ETIMEOUT | HTTP504 | Likely causeThe target site did not answer in time. | What to doRetry. For a slow page, render=never avoids the browser. |
When to retry
- Retry
EBUSY,ECIRCUITOPEN,ETIMEOUT,EUNREACHABLE,EBROWSERandEINTERNAL, with an increasing delay. - Retry
ERATELIMITafter the delay given by theretry-afterheader. - Do not retry the other 4xx codes: the same request will give the same error.