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 theRetry-Afterheader 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 afterRetry-After. More on this in Request limit: how the tiers work.insufficient_quotaorcredit_balance_exhausted: The available credit isn't enough for this request. Add credit, see Add credit and top up automatically.spend_limit_exceededorperiod_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 fromRetry-Afterand try again, or switch to a different model.routing_unavailable: FlowModels is temporarily switched off, for example for maintenance. No credit is reserved. Retry afterRetry-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.paramnames the field. This also includes a value that's too high formax_tokens.unsupported_for_model: The field is valid, but the chosen model doesn't accept it, for exampletemperatureon a model with fixed sampling.GET /v1/modelstells you which fields a model understands.unsupported_field: The field isn't supported by FlowModels at all.input_tokens_exceededorcontext_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 theAuthorization: Bearerheader.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.