Docs / Errors
Errors
Machine-readable Agent API errors with HTTP status, retryability, remediation, and compatibility fields.
Updated 2026-07-22
Canonical catalog
Fetch https://api.stakao.com/agent/errors.json for the Worker-generated error definitions tied to contract version 2026-07-22.
- invalid_request — 400.
- payment_required — 402.
- auth_required — 401.
- insufficient_scope — 403.
- not_found — 404.
- request_conflict — 409.
- preflight_required — 428.
- body_too_large — 413.
- rate_limited — 429.
- reference_unavailable — 503.
- origin_unavailable — 502/503.
Error definition
json
{"code":"preflight_required","http_status":428,"retryable":false,"remediation":"Call the free preflight endpoint first.","docs_url":"https://stakao.com/docs/errors"}Compatibility fields
Existing response fields remain available while canonical fields are added.
Error responses keep the legacy error field for existing clients. They also include code, retryable, remediation, and docs_url. JSON-RPC errors retain the JSON-RPC error object and use HTTP status only for transport-level failures.
Retry semantics
Use retryable and remediation together; do not blindly retry authentication or validation errors.
- payment_required: read the x402 challenge, pay, and retry the exact request.
- rate_limited: wait for Retry-After before retrying.
- reference_unavailable or origin_unavailable: retry later and do not make a payment assumption.
- auth_required or insufficient_scope: obtain the required OAuth consent and scope.
- preflight_required: call the free preflight endpoint before payment.
Unknown routes
The Worker returns a canonical not_found error for any route not declared in the contract.
Probe a route safely
bash
curl -i https://api.stakao.com/agent/not-declaredAgent entrypoints