​

Errors & Status Codes

​

Common status codes

​

Example error body

{
  "error": "The model provider is temporarily unavailable. Please try again in a moment."
}

{
  "error": "Temporary rate limit applied due to high load. Please retry shortly at a lower rate (up to 10 requests per minute).",
  "retry_after_seconds": 58,
  "max_rpm": 10
}

​

Important semantics

• Upstream failures never count against quota. A 529 “Overloaded” capacity response or a 502 upstream error does not consume your plan or credit balance.
• 429 has two causes:
  1. Plan rate limit — your key exceeded its per-window allowance, weekly cap, or per-minute burst limit. On-demand credits may allow continued use past the per-window allowance and weekly cap.
  2. Temporary abuse/capacity throttle — a short-lived lower per-minute cap applied to this key only when automated signals detect disproportionate high-volume load that may harm shared model capacity. Credits do not bypass this throttle. This is a rate reduction, not a block — the key keeps serving at the lower rate, so retry shortly at the reduced rate rather than waiting out the throttle. The response includes a short Retry-After header (seconds until your next retry, typically under a minute — not the full throttle duration) and retry_after_seconds / max_rpm fields in the body.
• 529 vs 429: Capacity issues return 529 Overloaded (with a Retry-After header) while we fail over or wait for providers to recover. They do not trigger the abuse throttle by themselves during platform-wide capacity events.

​

Capacity messages you may see

• “We’re experiencing heavy usage right now, which may cause increased latency or temporary unavailability…”
• “The model provider is temporarily unavailable…”

​

See also

• Rate Limits
• Troubleshooting