Errors

HTTP status codes and error shapes returned by the Ada AI API, with the recommended handling for each.

Errors are returned as JSON. The shape matches the surface you called:

/v1/models and /v1/chat/completions — OpenAI shape: { "error": { "message": "...", "type": "..." } }
/v1/messages — Anthropic shape: { "type": "error", "error": { "type": "...", "message": "..." } }

Status codes

Status	Meaning	Recommended handling
`400`	The caller has no upstream serving the requested model, or `model` is missing.	Check that you've enabled an upstream for that model and run Sync models.
`401`	Missing or invalid proxy key.	Verify the key; rotate it if compromised.
`429`	Rate-limited — by the proxy or by the upstream. Read the error body to tell which.	Back off using the `Retry-After` header or the interval in the body.
`502`	All upstreams that serve this model failed (after failover).	Retry with backoff; if persistent, check the upstream's status in the dashboard.

Other 4xx bodies are passed through from the upstream where possible (for example a 400 for malformed request bodies, or a 404 for an unknown model ID on a specific upstream during failover).

Examples

No upstream for the model (OpenAI shape)

{
  "error": {
    "message": "no upstream configured for model: gpt-5-hypothetical",
    "type": "invalid_request_error"
  }
}

All upstreams failed (OpenAI shape)

{
  "error": {
    "message": "all upstreams failed for model: glm-4.7",
    "type": "upstream_error"
  }
}

Rate-limited (OpenAI shape)

{
  "error": {
    "message": "rate limit exceeded",
    "type": "rate_limit_error"
  }
}

Distinguishing proxy vs. upstream rate limits

A 429 can come from either layer. Inspect the error body:

Proxy rate limit — the type is rate_limit_error and the message references your plan's limits. Back off and, if you hit this regularly, request a higher tier.
Upstream rate limit — the upstream's own error is surfaced, often with a provider-specific type. The proxy will not fail over to another upstream for a 429 (only for 5xx), so apply client-side backoff.

The proxy retries the next matching upstream only when an upstream returns a 5xx. 4xx responses (including 429 rate limits and 400 bad requests) are returned to the caller immediately — they're not retried, because they usually indicate a problem with the request itself rather than the upstream being down.

Invalid model never substitutes

If you request a model that none of your enabled upstreams serve, you get a 400 — not a fallback to a similar model. Ada AI never silently changes the model you asked for. To use a different model, request it explicitly (and make sure an upstream serves it).