Errors
Every error response is JSON with an error message. A refused request also carries a stable code. Read the status first, then the code.
How to read an error
The HTTP status says where the problem is.
4xxThe request or the scanned site is the problem. The code says which.429A limit was reached. TheRetry-Afterheader says how many seconds to wait.5xxA failure on ora's side. Retry later.
Branch on code. The error message is written for people and can change. A code does not.
When a scan API key's limit is used up, the response is 429 with error: "usage_limit_reached". See Usage limits.
Scan errors
A scan that ora refuses says why with one of these codes.
POST /api/scan and POST /api/scan/checks return them with status 400. On GET /api/scan/stream, a refused target arrives as code on the error event, with one of the DOMAIN_ codes or INVALID_URL.
INVALID_INPUTThe request body is not valid JSON, is missing a field or holds a wrong value. The response also carriesdetails, which names the problem.INVALID_DOMAINTheurlis not a domain ora can scan.DOMAIN_UNREACHABLEThe domain did not respond, or its name does not exist.DOMAIN_LOOKUP_FAILEDThe DNS lookup did not finish, so ora could not check the domain. The same request can succeed later.DOMAIN_PRIVATE_ADDRESSThe domain points to a private or internal address. Ora scans public sites only.DOMAIN_REDIRECT_LOOPThe domain redirects in a loop.INVALID_URLThe target could not be read as a site or as an MCP server. The response also carriesreason.
These codes describe the request or the site. DOMAIN_LOOKUP_FAILED is the exception: ora could not finish the check, so retry later.
A scan can return three more codes:
EPHEMERAL_CLOBBER400. The request setephemeral: truefor a domain that already has a stored scan. Drop the flag.UNKNOWN_CHECK_IDS400onPOST /api/scan/checks. A check id is not in the catalog. The response names it, andGET /api/checkslists the valid ids.scoring_version_unavailable400. ThescoringVersionyou asked for is not published. The response lists the published versions.