Errors
The error envelope and the codes you'll actually see.
Every error is JSON with a stable envelope:
{
"error": "machine_readable_code",
"message": "Human-readable explanation",
"trace_id": "01JXYZ…"
}trace_id is also returned as the X-Trace-Id header on every response —
include it when reporting issues.
Codes
| HTTP | error | When |
|---|---|---|
| 400 | validation_error | Request didn't match the schema — includes an issues array (see below) |
| 401 | auth_required | No session cookie or API key on a gated route |
| 403 | plan_required | Your plan doesn't include this feature (Builder, Compare, full metrics, webhooks) |
| 404 | not_found | No such route or resource |
| 429 | rate_limited | See Rate limits — honor Retry-After |
| 5xx | internal_error | Our fault. Retry with backoff; report persistent trace_ids |
The x402 agent tier adds 402 (payment required), 451
(payer blocklisted), and payment-specific errors.
Validation errors
{
"error": "validation_error",
"issues": [
{ "path": "params.proxy", "message": "invalid proxy address", "code": "custom" }
],
"trace_id": "01J…"
}Each issue carries the JSON path, a message, and a zod issue code.