Error handling

Error handling

Errors are consistent JSON objects.

x402 errors are always returned as 402.

Standard error responses

Status	Meaning	Example
400	Bad Request	{ "message": "Validation error", "errors": [...] }
401	Unauthorized	{ "error": "unauthorized", "message": "Valid Otonix API key required" }
402	Payment Required	x402 requirements payload
403	Forbidden	{ "error": "forbidden", "message": "API key does not own this agent" }
404	Not Found	{ "message": "Agent not found" }
410	Gone (Deprecated)	{ "error": "deprecated", "message": "Use POST /api/agents/register" }
500	Server Error	{ "error": "Internal server error message" }
503	Service Unavailable	{ "error": "Cherry Servers not configured" }

400 validation error shape

{
  "message": "Validation error",
  "errors": [
    { "path": "domain", "message": "domain is required" }
  ]
}

x402 payment errors

All x402 errors return 402.

Error codes

• payment_required — missing X-Payment header.

• payment_invalid — any verification failure.

Common reasons

• Order ID expired (TTL 15 minutes).

• Order ID does not match this endpoint.

• Transaction already used for a previous purchase.

• Transaction failed on-chain.

• Transaction sender does not match claimed payer.

• Insufficient amount sent.

Example: expired order

{
  "error": "payment_invalid",
  "message": "Order expired",
  "extra": { "orderId": "a1b2c3..." }
}

Client-side, handle 402 as a state machine. Don’t treat it as an exception.