On this page

Error codes

Every error has the same JSON shape, including on the endpoints that return an image or a PDF.

Response
{
  "status": "fail",
  "code": "EFORBIDDENURL",
  "message": "Destination is not allowed"
}
  • status is fail when the request is at fault (4xx), error when the server or the target is at fault (5xx).
  • code is stable: it is what your code should test.
  • message is in English, meant for humans, and may change.

Causes and fixes

CodeHTTPLikely causeWhat to do
EINVALIDPARAMSHTTP400Likely causeA parameter is missing or has an invalid value.What to doCompare the request with the reference; the message names the parameter.
EINVALIDURLHTTP400Likely causeThe url is malformed or is neither http nor https.What to doSend an absolute address and encode it (encodeURIComponent).
EUNAUTHORIZEDHTTP401Likely 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.
EFORBIDDENURLHTTP403Likely 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.
EEMBEDNOTFOUNDHTTP404Likely 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.
ESELECTORNOTFOUNDHTTP404Likely causeThe selector matches no visible element.What to doCheck the selector in a browser; add waitForSelector if the element appears late.
ENOTHTMLHTTP422Likely 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.
ETOOLARGEHTTP422Likely causeThe PDF or the generated output exceeds the maximum size.What to doMake the page smaller: turn printBackground off, or target a shorter page.
ERATELIMITHTTP429Likely causeToo many requests in the current window.What to doWait for the retry-after delay. Cache your results, or use a key.
EBROWSERHTTP500Likely causeChromium crashed or could not start.What to doRetry. If the error persists on your instance, check the Chromium installation.
EINTERNALHTTP500Likely causeUnexpected server error.What to doRetry; if it happens again, open an issue with the x-request-id header of the response.
EUNREACHABLEHTTP502Likely 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.
ETARGETSTATUSHTTP502Likely 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.
EBLOCKEDHTTP502Likely 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.
ECIRCUITOPENHTTP503Likely 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.
EROUTENOTFOUNDHTTP404Likely causeThe requested path does not exist in the API.What to doCheck the path and version (/api/v1/…) in the reference.
EBUSYHTTP503Likely causeToo many renders are queued on the instance.What to doRetry after a few seconds, with an increasing delay.
ETIMEOUTHTTP504Likely 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, EBROWSER and EINTERNAL, with an increasing delay.
  • Retry ERATELIMIT after the delay given by the retry-after header.
  • Do not retry the other 4xx codes: the same request will give the same error.

Keyboard shortcuts

CtrlKor/
Open search and commands
?
Show this help
←→
Move from one tab to the next
Ctrl↵
Run the request in the playground
Esc
Close a panel or a menu

Single-key shortcuts can be turned off in the accessibility options.