API reference
Errors
Every error code the API returns and what to do about it.
Errors return an OpenAI-style body:
{ "error": { "message": "Insufficient credits", "code": "insufficient_credits" } }
Anthropic-dialect calls (/api/messages) return the Anthropic error shape instead —
same statuses, same semantics:
{ "type": "error", "error": { "type": "insufficient_quota", "message": "Insufficient credits — top up at runaii.cloud/console/billing." } }
| HTTP | code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_request |
Malformed body / missing messages |
Fix the request shape |
| 400 | unknown_model |
Unpriced model id — only the legacy session path (/api/chat) answers this; the /v1 API remaps the same case to 404 model_not_found |
Use an id from GET /api/v1/models |
| 404 | model_not_found |
Model id unknown, hidden, or unpriced (all treated as nonexistent) | Use an id from GET /api/v1/models |
| 401 | invalid_api_key |
Missing, malformed, or revoked key | Re-mint at Console → API Keys |
| 403 | key_scope_denied |
Key lacks the inference scope (e.g. a deployments-only key) |
Mint an inference-scoped key |
| 402 | insufficient_credits |
Balance can't cover the estimate | Top up at Console → Billing |
| 402 | lkm_key_missing |
Account provisioned but no inference key yet | A top-up provisions one automatically |
| 402 | daily_cap / daily_limit / key_budget_exceeded |
Per-key cap hit (balance is fine) | Raise the cap or wait for reset |
| 429 | rate_limited |
> 180 req/min on this key (60 on welcome credits) | Back off; pay once to lift the tier |
| 502 | upstream_error |
Inference cell failed | Retry — failed requests are auto-refunded |
| 503 | upstream_warming |
Engine warming up (scale-from-zero) | Retry with backoff (Retry-After header provided) |
| 503 | billing_unavailable |
Billing DB briefly unreachable | Never a free pass — retry shortly |
Semantics that matter
- Fail-closed billing: if our billing plane is down you get
503, never free inference. We consider that a feature. - Refund guarantees: any request that errors (
502,503, mid-stream death) is refunded atomically. Verify with the ledger at Console → Billing. - Idempotency: retried requests create new reservations — dedupe on your side by not re-sending the same logical request unless the first errored.