# Errors and billing semantics

Every error has one shape:

```json
{"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`).
