Errors
HTTP status codes and common API failure modes.
FastAPI returns JSON { "detail": "..." } on errors. SSE chat streams emit an error event before closing.
HTTP status codes
| Code | Meaning | Typical cause |
|---|---|---|
| 400 | Bad Request | Invalid tool arguments, chat persistence failure, malformed reissue proof |
| 403 | Forbidden | Missing or invalid X-Agent-Access-Token on protected routes |
| 404 | Not Found | Agent or conversation does not exist |
| 410 | Gone | Agent is soft-deleted (inactive) |
| 422 | Unprocessable Entity | Missing required fields (e.g. agent_id on chat) |
| 503 | Service Unavailable | OpenAI upstream failure or RPC service unavailable |
Tool-level failures
Tools return structured JSON with success: false and a message field for RPC errors, cap violations, insufficient balance, or testnet URL rejection on write tools in production.