Skip to main content
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.

​
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 key’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:
HeaderMeaning
Retry-AfterSeconds to wait before retrying.
x-ratelimit-limit-requestsRPM ceiling.
x-ratelimit-remaining-requestsRemaining in the current window.
x-ratelimit-reset-requestsUnix 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.