| code | meaning | do |
|---|---|---|
400 | Malformed request — includes a provider rejecting a pasted credential (their verdict is quoted) | fix and retry |
401 | Missing/invalid API key | re-authenticate |
402 | Plan quota exhausted (hard stop — we never bill silent overage; opt in explicitly to continue) | upgrade / opt in / wait for the period |
403 | Your key can't do this (scope, or a frontier call with no usable provider credential — the error names the provider and the fix) | don't retry unchanged |
404 | No such resource | — |
413 | A knowledge quota (named: document_too_large, set_quota_exceeded, knowledge_quota_exceeded) | trim or upgrade |
422 | Schema validation | fix the request |
429 | Rate limited | back off |
503 | A dependency unreachable (e.g. the provider during credential validation — nothing was stored) | retry with backoff |
Two guarantees worth designing around: no mid-stream failover (once the first token streams, a failure is surfaced, never silently retried on another backend), and your credentials only ever pay for your own calls — a request that can't be served on your keys fails; it is never served on ours.