Errors

Error bodies follow the OpenAI envelope:

{ "error": { "message": "insufficient balance", "type": "invalid_request_error", "code": "..." } }

Status codes

Code	Meaning	What to do
400	Bad JSON or unsupported field combination	Fix the body
401	Missing / unknown / revoked key	Mint a new key
402	Insufficient balance	Top up
404	Unknown path, or `model_not_found`	Check `/v1/models`
429	Host concurrency cap	Back off, or enable persist
502	Upstream / no host / fallback failed	Retry later; check Status
504 / client timeout	Host too slow or prompt too large	Raise client timeout; shrink context

Messages you will actually see

insufficient balance — credit is gone, including over-limit image conversion
model_not_found — id is deprecated or the network unlisted it (0 healthy shards)
rate limit exceeded: too many concurrent requests (N/N) — the host is full, not a proxy QPS quota
router upstream error / no currently-available host — routing failed after retries
inference: no non-probe attempt finished — hosts accepted then died

Retry policy

Retry 429 and 502 with jitter. Do not retry 401 or 402. Do not tight-loop 404 model_not_found — wait for the model to return on /v1/models.

Status vs your request

The Status page can show a model as “healthy” (shards exist) while your request still 429s. Health is inventory. 429 is a full queue.