EXTRACTION_FAILED

The cleaning engine errored mid-process — rare, usually transient.

What this means

EXTRACTION_FAILED indicates an internal error inside the cleaning engine itself — the page was fetched successfully, but cheerio failed to parse it, or the AIO scorer crashed on malformed input. This is rare (<0.1% of requests) and almost always transient. We log every occurrence and investigate; if the same URL fails repeatedly, that's a bug we want to know about.

When you'll see it

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

Example response

{
  "status": "error",
  "code": "EXTRACTION_FAILED",
  "message": "Cleaning engine failed to parse the response"
}

How to handle

Retry once with `"fresh": true` in the request body — this bypasses our cache and re-fetches the page, which fixes the issue if the cached version was corrupt. If the error persists across multiple retries, that's a bug — file an issue with the failing URL at github.com/ravixalgorithm/onto-api or email founder@buildonto.dev.

Suggested handling in a Node client:

if (data.code === 'EXTRACTION_FAILED') {
  // Transient; retry once with fresh=true.
  return retry({ fresh: true });
}

Related errors

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