Errors and billing semantics
Every error has one shape:
{"ok": false, "request_id": "req_…",
"error": {"code": "insufficient_balance", "message": "…", "retryable": false, "billed": false}}
billed is always false for errors: invalid input is rejected before charging, and source failures are refunded automatically.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_input, invalid_idempotency_key | Bad parameters |
| 401 | unauthorized | Missing, wrong, disabled or expired key |
| 402 | insufficient_balance | Wallet too low; top up |
| 402 | trial_cap_reached | Agent trial budget spent; body has upgrade |
| 402 | spend_cap_exceeded | This key's spend limit reached |
| 402 | max_cost_exceeded | Call costs more than max_cost_usd; body has price_usd |
| 403 | forbidden, signup_disabled | Access level or server policy |
| 404 | not_found, result_expired | Unknown id, or stored result past retention |
| 409 | idempotency_conflict, idempotency_in_progress, primary_key | See Running / API keys |
| 422 | invalid_input, site_unreachable | Validation; the audited site could not be fetched (refunded) |
| 429 | rate_limited | Per-key limit; honour Retry-After |
| 501 | not_available, billing_not_configured | Not offered in this mode/server; not charged |
| 502 | provider_unavailable | Source failed; refunded; retryable |
| 500 | internal_error | Unexpected; retryable |
A partial report (an optional source failed) is a success: charged, with output.partial: true and the failures listed.
Rate limit: 120 requests/minute per key by default (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset).
Plain Markdown for agents: /docs/errors.md · index: llms.txt