Errors

All errors use OpenAI’s envelope: { "error": { "message": "...", "type": "...", "code": "..." } }.

400 — Bad request

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

{
  "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.

Prompt longer than the context window

A prompt above the model’s context window is refused with a 400 before any tokens are generated, so you are not billed for it. The message comes from the serving engine, which names the limit and what you sent:

{
  "error": {
    "message": "This model's maximum context length is 131072 tokens. However, you requested 154238 tokens.",
    "type": "invalid_request_error",
    "code": null
  }
}

What to do: shorten the prompt, or split the work across requests. Read each model’s limit from the API rather than hard-coding a number — it’s context_length on GET /v1/models (see model discovery) — because a model’s window can change when we move it to different hardware. Note that the window covers the prompt and the completion together: if you ask for max_tokens on top of a prompt that nearly fills the window, the request can still be refused.

401 — Unauthorized

Missing, malformed, or revoked API key.

{
  "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.

402 — Payment required

Your account’s credit is exhausted.

{
  "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. The same key resumes working after the balance is restored.

404 — Not found

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

{
  "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 for this key.
`x-ratelimit-remaining-requests`	Remaining in the current window.
`x-ratelimit-reset-requests`	Unix timestamp when the window resets.

{
  "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.

500 — Internal server error

Unexpected failure in our gateway or an upstream model backend.

{
  "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.

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.

Get Started

Guides

Reference

Chat

Completions

Embeddings

Models

Usage

400 — Bad request

Prompt longer than the context window

401 — Unauthorized

402 — Payment required

404 — Not found

429 — Too many requests

500 — Internal server error

503 — Service unavailable

​400 — Bad request

​Prompt longer than the context window

​401 — Unauthorized

​402 — Payment required

​404 — Not found

​429 — Too many requests

​500 — Internal server error

​503 — Service unavailable

400 — Bad request

Prompt longer than the context window

401 — Unauthorized

402 — Payment required

404 — Not found

429 — Too many requests

500 — Internal server error

503 — Service unavailable