# Chatito Agent API — error codes

**Host:** https://chatito.ai/errors.md  
**See:** [agent-api.md](https://chatito.ai/agent-api.md)

| Code | HTTP | Meaning |
|------|------|---------|
| `unauthorized` | 401 | Missing, invalid, revoked, or expired agent key |
| `forbidden` | 403 | Valid key but not allowed |
| `scope_required` | 403 | Missing required scope (e.g. paper_trade on Phase 2+) |
| `not_found` | 404 | Unknown or not-owned resource |
| `rate_limited` | 429 | Per-minute or monthly budget exceeded |
| `capacity_exceeded` | 409 | Too many keys or plan capacity |
| `validation_error` | 422 | Bad query/body |
| `live_scope_required` | 403 | Live action without live scope (future) |
| `live_not_armed` | 409 | Live scope but human has not armed (future) |
| `venue_unavailable` | 503 | Heat/upstream venue down |
| `insufficient_credits` | 402 | Invent (or other Lab) needs more AI credits |
| `credits_error` | 402 | Credit system rejected the spend |
| `agent_api_disabled` | 503 | Feature flag off |
| `internal_error` | 500 | Server fault (no stack traces) |

Envelope shape: see agent-api.md.