Skip to main content
The Flowy API uses conventional HTTP status codes to indicate the success or failure of a request. The status code is the machine-readable signal; every error also returns a human-readable error message in the body:
In general: 2xx means success, 4xx means the request was rejected and usually tells you how to fix it, and 5xx means something went wrong on Flowy’s side.

​
Status codes

Problem: None: the request succeeded. 202 Accepted is returned when a run is accepted for processing; 200 OK for everything else.Solution: For a 202, poll Get a run until its status is completed or failed.
Problem: The request was malformed, or a params entry (see Get a flow’s params[]) doesn’t satisfy its schema. An unrecognized or missing inputs entry does not land here. See the note below.Solution: Check the request body against the flow’s schema. inputs must be an array of entries, each with a node_id (an input’s name) and a value asset_url for media inputs or prompt for text inputs. params must be an object keyed by a param’s name, each value matching its kind. Two codes cover it, both with a details: { field, expected, received } alongside error:
  • invalid_body: the body isn’t valid JSON, or inputs / params has the wrong shape (inputs must be an array or an object, params an object).
  • unknown_param: the key isn’t any of the flow’s published param names; error lists the valid ones.
  • invalid_param: the value doesn’t satisfy the param’s kind (wrong type, out of min/max, off the step, or not one of enumValues).
Problem: An inputs entry names a node_id the flow doesn’t have, or a required content input was left out.Solution: Nothing to fix necessarily: this never fails the request. The 202 response carries a warnings array instead (code: "unknown_input" or "missing_input", plus field and message), and the run starts anyway using the flow’s published content for anything missing. Read warnings if you want to catch a typo’d node_id early.
Problem: The API key is missing, malformed, revoked, or expired.Solution: Send the key in the Authorization: Bearer flowy_… header and confirm it’s still active under Settings → API keys.
Problem: The key hit its daily spend cap, or the workspace is out of credits.Solution: Raise the key’s cap, top up the workspace’s credits, or wait for the next UTC day. The available balance is the hard backstop. When it reaches zero, runs stop regardless of any cap.
Problem: The request is authenticated but not allowed. Common causes: the key lacks the required scope; the flow is private and not in the key’s workspace; the run belongs to another workspace; or a publishable key was used from a domain that isn’t allowlisted.Solution: Grant the key the needed scope, use a key from the flow’s own workspace, or call from an allowed domain.
Problem: No flow or run matches the appId / runId in the path.Solution: Double-check the id. List flows with List flows, and use the runId returned by Start a run.
Problem: You exceeded the key’s per-minute request limit or its concurrent-run limit.Solution: Back off and retry after the Retry-After interval. Watch the X-RateLimit-Remaining header and keep in-flight runs under the limit. See Rate limits.
Problem: Something went wrong on Flowy’s side.Solution: Retry after a short delay. If it persists, contact support with the time of the request.

​
Handling failed runs

A run can also fail after it starts: for example, an upstream generation error. In that case the run reaches status: "failed" with a human-readable error field; poll Get a run to read it. Credits for a failed generation are refunded to the workspace automatically.
Last modified on September 8, 2026