Agent API

Error Handling & Codes

Verdict uses deterministic, sanitized error structures. Internal model internals, provider stack traces, and private prompts are never exposed to API consumers.

Standard Error Response Format

All errors return a standard JSON object containing a machine-readable code and human-readable message:

Error Response

{
  "error": {
    "code": "INVALID_URL",
    "message": "The URL is not auditable"
  }
}

Sanitized Error Catalog

Status	Code	Message & Recovery Strategy
400	INVALID_REQUEST	Invalid JSON body or unexpected request shape. Ensure the request body is valid JSON with exactly one 'url' field.
400	INVALID_URL	The URL is not auditable or violates URL security policies. Provide a public HTTP or HTTPS startup URL. Private IPs, localhost, and non-web schemes are rejected.
402	PAYMENT-REQUIRED	Payment challenge issued via the x402 protocol (PAYMENT-REQUIRED header). Sign and attach the PAYMENT-SIGNATURE header authorization for $0.50 USDC on Base.
422	AUDIT_UNAVAILABLE	The startup could not be audited (unreachable or blocked extraction). Verify the target website is publicly online and not blocking headless browser verification.
503	AUDIT_TEMPORARILY_UNAVAILABLE	The audit service is temporarily unavailable due to transient capacity limits. Retry the request with exponential backoff after a short delay.
500	AUDIT_FAILED	The audit could not be completed due to an unrecoverable internal error. Log the report error. Unsettled entitlements are released safely.
500	X402_CONFIGURATION_ERROR	The server encountered a configuration error with its x402 payment rail. Ensure server-side payment configuration and credentials are set correctly.