Errors & status codes - FortAPI

When a request fails, FortAPI tells you why with an HTTP status code plus a JSON error body. The body’s shape depends on the protocol you’re using.

Error body format

OpenAI protocol (/v1/chat/completions, etc.):

{
  "error": {
    "message": "insufficient user quota (request id: 2025...-abc)",
    "type": "insufficient_quota",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

Claude protocol (/v1/messages):

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "upstream temporarily overloaded, retry shortly"
  }
}

The message usually ends with a request id. Include it when contacting support — it’s the fastest way to locate that request’s logs.

Status codes

Status	Meaning	What to do
`401`	Auth failed: key missing, mistyped, disabled, or deleted	Confirm you’re using a FortAPI token (`sk-...`) with no stray whitespace/newlines; check it’s still enabled under Tokens in the console
`403`	Insufficient balance, token/account banned, or group has no access to that model	Top up, or switch to a model you have access to; check the token’s model allowlist doesn’t exclude it (insufficient balance is 403, not 402)
`404`	Model doesn’t exist, or wrong request path	Verify the model name (per the Pricing page); OpenAI `base_url` includes `/v1`, Anthropic SDK’s `ANTHROPIC_BASE_URL` does not
`429`	Rate limited (too many requests)	Back off and retry — see Rate limits
`500`	Internal server error	Usually transient; retry shortly. If persistent, contact support with the request id
`503`	No upstream channel available, or system overloaded	Retry shortly or switch models; if persistent, contact support
`529`	Upstream provider (e.g. Anthropic) overloaded — passed through verbatim, `type` is `overloaded_error`	A transient upstream state; exponential-backoff retry usually recovers

Telling which layer an error came from

Errors from FortAPI itself usually have type of new_api_error or a standard type (insufficient_quota, invalid_request_error, …).
Errors from the upstream provider (e.g. rate_limit_error, overloaded_error) are passed through verbatim, preserving the upstream status code and type, with per-channel retry where applicable. Seeing overloaded_error / rate_limit_error generally points to an upstream-side issue.

Retry guidance

For transient errors (429 / 500 / 503 / 529), retry with exponential backoff (e.g. 1s, 2s, 4s… with a little jitter) rather than hammering — tight retries make rate limiting worse. 401 / 403 / 404 are configuration errors; retrying won’t help — fix the config per the table above.