> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every 4xx and 5xx status we return, with an example body and what to do about it.

<Note>
  All errors use OpenAI's envelope: `{ "error": { "message": "...", "type": "...", "code": "..." } }`.
</Note>

## 400 — Bad request

Your request body is malformed, an unknown model was requested, or a required field is missing.

```json theme={null}
{
  "error": {
    "message": "Invalid 'model'. The model 'foo' does not exist or you do not have access.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}
```

**What to do:** fix the request. The `message` field is safe to surface in your UI.

## 401 — Unauthorized

Missing, malformed, or revoked API key.

```json theme={null}
{
  "error": {
    "message": "Invalid API key provided.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

**What to do:** check the `Authorization: Bearer sk-…` header. If the key is correct, it may have been revoked — generate a new one from the [dashboard](https://tokens.flex.ai/dashboard/keys).

## 402 — Payment required

Your key's credit is exhausted.

```json theme={null}
{
  "error": {
    "message": "Insufficient credit. Add funds at https://tokens.flex.ai/dashboard/billing to continue.",
    "type": "insufficient_quota",
    "code": "402"
  }
}
```

**What to do:** top up from the [billing page](https://tokens.flex.ai/dashboard/billing). The same key resumes working after the balance is restored.

## 404 — Not found

Typically a stale model id or an unknown video job id.

```json theme={null}
{
  "error": {
    "message": "Video job not found.",
    "type": "invalid_request_error",
    "code": "job_not_found"
  }
}
```

**What to do:** verify the id. Video jobs are retained for 24 hours after completion — older ids expire.

## 429 — Too many requests

You exceeded the per-key requests-per-minute ceiling. The response includes these headers:

| Header                           | Meaning                                |
| -------------------------------- | -------------------------------------- |
| `Retry-After`                    | Seconds to wait before retrying.       |
| `x-ratelimit-limit-requests`     | RPM ceiling.                           |
| `x-ratelimit-remaining-requests` | Remaining in the current window.       |
| `x-ratelimit-reset-requests`     | Unix timestamp when the window resets. |

```json theme={null}
{
  "error": {
    "message": "Rate limit exceeded. Retry after 34 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}
```

**What to do:** back off until `Retry-After`. If you consistently hit the ceiling, request a tier upgrade from [support@flex.ai](mailto:support@flex.ai).

## 500 — Internal server error

Unexpected failure in our gateway or an upstream model backend.

```json theme={null}
{
  "error": {
    "message": "Upstream model timed out.",
    "type": "server_error",
    "code": "upstream_timeout"
  }
}
```

**What to do:** retry with backoff (no idempotency key — so only retry idempotent requests, or accept the possibility of a double bill). Persistent 500s indicate an incident — check [status.flex.ai](https://status.flex.ai).

## 503 — Service unavailable

A specific subsystem is temporarily offline (e.g., a model under maintenance, or the playground disabled).

**What to do:** retry later. The `message` explains which subsystem.