Forge
Sign in
Advanced

Errors & limits

Forge returns OpenAI-style error envelopes. Status codes follow HTTP semantics; the body always includes a stable error code you can branch on.

Error envelope

jsonjson
{
  "error": {
    "code": "quota_exceeded",
    "message": "Daily quota reached. Resets in 4h 12m.",
    "type": "billing_error",
    "param": null
  }
}

Common codes

  • 401 unauthorized — missing or invalid API key.
  • 402 quota_exceeded — quota window depleted.
  • 403 model_not_allowed — key policy excludes this model.
  • 404 model_not_found — unknown vendor or model id.
  • 429 rate_limited — too many requests per second.
  • 502 upstream_error — provider returned a non-2xx.
  • 504 upstream_timeout — provider did not respond in time.

Rate limits

Default per-key limits: 5 RPS on Hobby, 60 RPS on Team, custom on Enterprise. Burst windows are 1 second; exceed it and you get 429 with a Retry-After header.

Retry guidance

  • Retry 429 and 5xx with exponential backoff (250ms → 4s).
  • Never retry 4xx other than 408 / 425 / 429.
  • Use a fallback chain (X-Forge-Route) instead of client-side retries when possible.