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.

  • 4xx The request or the scanned site is the problem. The code says which.
  • 429 A limit was reached. The Retry-After header says how many seconds to wait.
  • 5xx A failure on ora's side. Retry later.
A refused scan
{ "error": "Domain resolves to a private IP", "code": "DOMAIN_PRIVATE_ADDRESS" }

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_INPUT The request body is not valid JSON, is missing a field or holds a wrong value. The response also carries details, which names the problem.
  • INVALID_DOMAIN The url is not a domain ora can scan.
  • DOMAIN_UNREACHABLE The domain did not respond, or its name does not exist.
  • DOMAIN_LOOKUP_FAILED The DNS lookup did not finish, so ora could not check the domain. The same request can succeed later.
  • DOMAIN_PRIVATE_ADDRESS The domain points to a private or internal address. Ora scans public sites only.
  • DOMAIN_REDIRECT_LOOP The domain redirects in a loop.
  • INVALID_URL The target could not be read as a site or as an MCP server. The response also carries reason.

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_CLOBBER 400. The request set ephemeral: true for a domain that already has a stored scan. Drop the flag.
  • UNKNOWN_CHECK_IDS 400 on POST /api/scan/checks. A check id is not in the catalog. The response names it, and GET /api/checks lists the valid ids.
  • scoring_version_unavailable 400. The scoringVersion you asked for is not published. The response lists the published versions.