FlowModels

Understanding FlowModels error messages

Published on 11. November 2026

When FlowModels rejects a request, your application gets an HTTP status and an error description in JSON format. Here's how to read an error message and what the most common codes mean.

How an error message is structured

Every error response has the same shape, compatible with OpenAI:

{
  "error": {
    "message": "…",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "param": null
  },
  "flowai_request_id": "01HXYZ…"
}

What matters is error.code. For input errors, param names the affected field. The flowai_request_id is also in the x-request-id header. Store it in your logs and include it in support requests. You'll find the same identifier in the request log.

429: Too many requests or no budget

A 429 has two very different causes, so always look at the code.

  • rate_limit_exceeded: Your tier's per-minute quota or the key's own limit is used up. Wait as many seconds as the Retry-After header states and try again.
  • concurrent_requests_exceeded: As many requests are already running at the same time as your tier allows. Send fewer in parallel and retry after Retry-After. More on this in Request limit: how the tiers work.
  • insufficient_quota or credit_balance_exhausted: The available credit isn't enough for this request. Add credit, see Add credit and top up automatically.
  • spend_limit_exceeded or period_spend_limit_exceeded: The key's monthly limit or your team's spending limit has been reached. A top-up doesn't help here. Raise the limit or wait until the month changes, see Set up a spending limit and warning thresholds.

Don't automatically retry requests with budget errors in a loop. They'll keep failing until you change the credit or the limit.

503: Temporarily no capacity

  • provider_overloaded: The provider of the chosen model has no capacity at the moment. This has nothing to do with your account. Wait the seconds from Retry-After and try again, or switch to a different model.
  • routing_unavailable: FlowModels is temporarily switched off, for example for maintenance. No credit is reserved. Retry after Retry-After.
  • pricing_unavailable: There is currently no reliable price for the model. Try again later.

With 502 routing_execution_failed, the request couldn't be completed, usually because the provider didn't answer. Here too, a later retry often helps. FlowModels doesn't switch to a different model on its own, it passes the error on to you.

400: The request is malformed

A 400 means something is wrong with your request. Retrying without changes won't help.

  • invalid_field_value: A field has an invalid value or a required field is missing. param names the field. This also includes a value that's too high for max_tokens.
  • unsupported_for_model: The field is valid, but the chosen model doesn't accept it, for example temperature on a model with fixed sampling. GET /v1/models tells you which fields a model understands.
  • unsupported_field: The field isn't supported by FlowModels at all.
  • input_tokens_exceeded or context_length_exceeded: The input is too large for the model. Shorten the history or the content you send along.

401, 403, 404 and 410

  • 401 invalid_api_key: The key is unknown, expired or revoked. Check it under API keys.
  • 401 invalid_token_source: The key wasn't passed in the Authorization: Bearer header.
  • 403 insufficient_key_scope: The key has the wrong permission, for example Manage keys instead of Use AI for a model call.
  • 403 account_suspended: Your team's access to FlowModels is suspended. Billing then shows Access suspended. Contact support.
  • 404 model_not_found: The model identifier doesn't exist. Check it under Models.
  • 410 model_deprecated: The model has been retired and can no longer be called. Switch to a different model.

Good to know

The full list of all codes is in the documentation at https://flowmodels.one/en/docs. If you retry POST requests after a dropped connection, send a fixed Idempotency-Key per operation. That way, a request that already succeeded isn't run and billed a second time.

Was this article helpful?

Back to Models, limits & errors