Error catalog
Every error, and what unblocks it
All errors are structured JSON with error, message, and context; the message states the fix. Markdown twin: /errors.md.
| code | HTTP | unblock |
|---|---|---|
| PAYMENT_REQUIRED | 402 | Balance too low. Relay human_readable to the user verbatim; retry the SAME call after top-up (or enable auto-refill at the enable_url). |
| UNAUTHORIZED | 401 | Missing/invalid bearer. Get a token via POST /v1/signup; send it as Authorization: Bearer <token>. |
| AGENT_KILLED | 403 | The operator killed this agent token. Only the operator can revive it (/revive in the operator Telegram). |
| AGENT_REVOKED | 403 | Token permanently revoked. Ask the account operator for a new agent token. |
| POLICY_DENIED | 403 | A per-agent cap or allowlist blocked the call BEFORE dispatch. The body says which rule and who can raise it. |
| DAILY_CAP_REACHED | 429 | The account daily spend cap is hit. Resets 00:00 HKT; the operator can raise it via PUT /v1/policies. |
| RATE_LIMITED | 429 | Too many requests (60/min per token; 10/min unauthenticated per IP). Back off and retry in a minute. |
| UNKNOWN_API | 404 | No such slug. Discover slugs with GET /v1/search?q=. |
| API_PAUSED | 503 | This capability is temporarily paused (spend alarm or provider issue). Check GET /status; try another slug. |
| API_UNAVAILABLE | 503 | The capability is not configured on this deployment. Check /capabilities for what is live. |
| BYOK_REQUIRED | 402 | This slug needs YOUR provider key. Ask for a one-time vault link (get_vault_link / POST /v1/keys/link) — never paste keys into chat. |
| VAULT_KEY_MISSING | 409 | No vaulted key for this provider on this account. Same fix: one-time vault link. |
| KEY_UNREADABLE | 500 | The vaulted key could not be decrypted. Re-vault it via a fresh link; contact support if it repeats. |
| LINK_INVALID | 400 | Vault link malformed/expired (10-minute TTL). Request a new one. |
| LINK_USED | 409 | Vault links are single-use. Request a new one. |
| PROVIDER_ERROR | 502 | The upstream provider failed. Your debit is refunded automatically; retry, or check /status for a cluster. |
| RESPONSE_TOO_LARGE | 502 | Upstream response exceeded the proxy cap (default 2MB). Narrow the request. |
| PROXY_UNKNOWN_PROVIDER | 404 | No such proxy route. See PROXY routes in /llms-full.txt. |
| PROXY_BAD_PATH | 400 | The proxy path failed safety checks (no .., no absolute URLs). |
| REQUEST_CAP_REACHED | 429 | Daily request cap for an unpriced route. Resets 00:00 HKT. |
| CONSENT_REQUIRED | 400 | Auto-refill needs the saved-card consent flow first: open the enable_url (/mandate?ref=...). |
| BALANCE_CAP | 409 | The top-up would exceed the account balance cap ($100 default). Spend down first; over-cap Stripe payments park for review. |
| EMAIL_EXISTS | 409 | Account exists. Use the existing token, or POST /v1/token/rotate if it was lost. |
| SIGNUPS_PAUSED | 503 | Trial-abuse alarm paused signups. Try again later. |
| NOT_CONFIGURED | 503 | This deployment lacks a required secret for the feature. The operator has been signaled. |
| CONFLICT | 409 | The resource is already in the requested state (e.g. proposal already decided, refill already this period). |
| FORBIDDEN | 403 | Founder/operator-only surface. |
| BAD_REQUEST | 400 | The body/params are malformed; the message names the exact field shape expected. |
| NOT_FOUND | 404 | No such resource, or not yours (tickets and mandates are account-private). |