Errors -- Verify API

Not one uniform envelope

Verify has no single global exception handler, so the error body is whatever the failing route itself raised. Two real shapes exist side by side: {"error": "<code>", "message": "..."} for validation/business errors, and a plain string for authentication failures (for example {"detail": "Missing bearer token"}). Both are wrapped by FastAPI's default {"detail": ...} envelope. Documented here as the real, current contract -- not smoothed into a single idealized shape.

400 -- invalid target / SSRF restriction (audit endpoints)

POST /v1/audits/mcp and POST /v1/audits/readiness return 400 for a rejected target, with detail.error set to one of:

• remote_url_required, public_https_url_required, url_credentials_or_fragment_blocked, invalid_port, https_port_required
• ssrf_host_blocked -- target host is not public (localhost/.local/.internal/cloud metadata hosts)
• dns_resolution_failed, invalid_resolved_ip
• ssrf_ip_blocked -- target resolves to a non-public address (private/loopback/link-local/multicast/reserved/unspecified)

422 -- invalid target / SSRF restriction (Watch)

The identical target-validation failures on /v1/watch/* routes return 422, not 400 -- a real, deliberate cross-surface difference from the audit endpoints above, not a typo to be normalized away in these docs. 422 is also returned for a malformed cursor, an empty PATCH body, and other request-shape validation failures on Watch.

401 -- unauthenticated

Shape differs by which token system rejected the request.

• Audit JWT: {"detail": "Missing bearer token"} or {"detail": "Invalid or expired token"}.
• Watch API key: {"detail": "missing_bearer_token"}, {"detail": "invalid_or_revoked_api_key"}, or {"detail": "expired_api_key"}.

403 -- insufficient scope / entitlement

• Audit JWT missing scope: {"detail": "Token missing required scope. Need one of: verify:audit"} (or verify:readiness).
• Watch key missing scope: {"detail": "api_key_missing_required_scope: need one of watch:read, watch:write"}.
• Watch plan/entitlement limit reached (for example, too many active watches): {"error": "watch_limit_reached", "limit": <n>} -- a different kind of 403 from a missing scope.

404 -- not found

Returned for an unknown or archived (soft-deleted) watch/policy id, and for any route path that does not exist.

409 -- conflict (Watch)

• watch_already_exists -- a non-archived watch already exists for that target/evaluator pair; body includes the existing watchId.
• watch_not_active -- attempted to run a paused or archived watch.
• watch_policy_name_exists -- a policy with that name already exists for the organization.
• watch_policy_in_use -- attempted to delete a policy a watch still references.

429 -- rate limited

Not currently applied to the audit or Watch API routes themselves -- these codes are real, but on adjacent legacy/public endpoints: scan_rate_limited (free public scan form), team_creation_rate_limited, watch_rate_limited (the older email-subscription flow, unrelated to the /v1/watch/* API above), and contact_rate_limited.

5xx -- server/provider failure

verify_dependency_unavailable or verify_audit_failed (both 503) from POST /v1/audits/mcp mean Verify itself could not complete the check against the target -- this is Verify's own failure to complete evaluation, not a finding about the target, and is distinct from a 400 SSRF rejection. Internal stack traces and provider secrets are never included in an error body.