Every error from api.ambient.xyz maps to a specific cause and a specific
reaction.
Error taxonomy#
| Status | Signal in the body | What it means | What to do |
|---|---|---|---|
401 / 403 | authentication_error or similar | Key missing, invalid, or revoked | Re-check the key; create a new one at app.ambient.xyz/keys |
402 (or a 403 whose message mentions funds/quota) | "insufficient funds", "quota" | Account out of funds | Top up; check the funds wording before classifying a 403 as an auth failure |
400 | "context", "context_length", "maximum context", "too long" | Input exceeds the model's context window | Trim the prompt, or pick a larger-context model from GET /v1/models |
400 | "Unknown model", invalid_request_error | The model id isn't in the catalog | Use an exact id from GET /v1/models (for example z-ai/glm-5.2) |
429 + "No workers available" | no-workers wording | Not a rate limit. No miners are serving that model right now | Switch to a model with is_ready: true; retrying the same model just waits for a worker to appear |
429 (plain) | rate-limit wording | You are sending too fast | Back off with jitter and retry |
5xx | None | Ambient-side failure | Retry cautiously; see below |
The two kinds of 429#
The distinction matters because the right reactions are opposites. A 429
with "No workers available" means your auth and pacing are fine; the model
simply has no live workers, so backing off doesn't help. Check
GET /v1/models (free, unauthenticated) and fail over to a ready model. A
plain 429 is classic rate limiting: slow down and retry the same request
with exponential backoff.
Parse the response body's message to tell them apart before choosing a strategy.
Retry guidance#
- Retry
502/503/504only for idempotent GETs (such asGET /v1/models), and only once or twice. - Do not blindly retry a timed-out completion POST. A request that timed
out on your side may still have been processed server-side, so a blind
retry can charge you twice for the same generation. If you must retry, do
it deliberately and log the
inference-idresponse header of every attempt so you can reconcile. - Treat mid-stream disconnects as truncation. Keep the partial output; see Streaming for stall and truncation detection.