URL_NOT_FOUND[01]

URL_NOT_FOUND

The target URL returned 404, or its hostname doesn't resolve.

Code · HTTP status · Retryable?
URL_NOT_FOUND[404][No]

What this means

[02]

URL_NOT_FOUND means the page isn't there. Either the origin answered 404, or the hostname has no DNS record, so there was nothing to connect to. The site isn't refusing you (that's WAF_BLOCKED or ROBOTS_BLOCKED); the page or host just doesn't exist. Failed requests are refunded.

When you'll see it

[03]

HTTP 404. Body always includes code: "URL_NOT_FOUND". Branch on code, never on the human-readable message — wording can change without notice; the code is the stable contract.

Example response

[04]
example response[json]
{
  "status": "error",
  "code": "URL_NOT_FOUND",
  "message": "Target URL returned 404: https://example.com/old-page"
}

How to handle

[05]

Check the URL is current and spelled right. Sites often move pages when they relaunch. If the URL used to work, the Wayback Machine may have a copy you can read instead. Don't retry the same URL.

Suggested handling in a Node client:

if (data.code === 'URL_NOT_FOUND') {
  // The page is gone; skip this URL.
  return null;
}
Code · Status · What it means
INVALID_URL[HTTP 400]

The url was missing or unparseable, used a scheme other than http(s), or pointed at a private or internal host.

WAF_BLOCKED[HTTP 403]

The target site refused Onto's crawler (the origin returned 401 or 403).

See the full error index for the complete catalog with the handling switch statement covering every code at once.