# Errors

Machine-readable Agent API errors with HTTP status, retryability, remediation, and compatibility fields.

Last updated: 2026-07-22

Canonical HTML: https://stakao.com/docs/errors
Raw Markdown: https://stakao.com/docs/errors.md

## Table of contents

- 01. [Canonical catalog](#catalog-shape)
- 02. [Compatibility fields](#compatibility)
- 03. [Retry semantics](#retry)
- 04. [Unknown routes](#unknown-routes)

## 01. 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"}
```

## 02. 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.

## 03. 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.

## 04. 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-declared
```

## Agent entrypoints

- [Agent manifest](https://api.stakao.com/agent): Worker-generated discovery manifest and safety metadata.
- [Agent OpenAPI](https://api.stakao.com/agent/openapi.json): Canonical REST contract generated by the Worker.
- [Agent llms.txt](https://api.stakao.com/agent/llms.txt): Worker-generated operational instructions.
- [Agent errors](https://api.stakao.com/agent/errors.json): Machine-readable error codes and remediation.
- [Public MCP](https://api.stakao.com/agent/mcp): Unauthenticated read-only MCP transport.

## Related Stakao references

- [AI Agents](https://stakao.com/docs/ai-agents): Start here for the complete agent flow.
- [Docs hub](https://stakao.com/docs): Canonical technical documentation index.
- [Full Markdown corpus](https://stakao.com/llms-full.txt): Complete docs and safety corpus.
- [Strategies Markdown](https://stakao.com/strategies.md): Generated strategy catalog.

## Related blog articles

- [Agent-native staking API](https://stakao.com/blog/agent-native-staking-api): Editorial context for the public agent API.
- [x402 payments for AI agents](https://stakao.com/blog/x402-payments-for-ai-agents): Editorial context for x402 payment retries.
- [MCP server for crypto staking agents](https://stakao.com/blog/mcp-server-for-crypto-staking-agents): Editorial context for the public MCP surface.