A run or an item failed — what the reason means
Every failure carries a class, and the class tells you whether retrying is sensible, pointless, or the very thing that would cost you money.
In this article (5)
FlowArray classifies every provider failure, and the class is what decides its own behaviour — so reading it tells you what to do.
The classes
| Reason | What happened | What to do |
|---|---|---|
| rate_limited | The provider said "too fast" (429) | Nothing. FlowArray cooled that key down — honouring the provider's own timing where it sends one — and carried on with the rest of the pool. If it happens constantly, lower that key's requests-per-minute or add a legitimately separate key |
| transient | A blip: timeout, 5xx, dropped connection | Already retried per the step's retry setting. Retry failed on the run if some items still failed |
| invalid_input | The provider refused the request as malformed | Not retried — it would fail identically. Check the resolved input in the Data tab: usually an empty required field or an image that is not really an image |
| content_policy | The provider refused on its own content rules | Not retried. Reword the prompt or change the reference image |
| auth | The key was rejected | Not retried. An admin should check the key on the API keys page — expired, revoked, or wrong provider |
| budget | A spend ceiling was reached | Working as intended. Raise the limit deliberately or wait for the rolling window to move |
| unknown | Something unclassified | Retry once; if it repeats, the run page carries the provider's own message |
Why some things are deliberately not retried
Retries on a paid generation call can charge you twice for one result. So FlowArray only retries what is safe to repeat: transient network-level failures and rate limits. A refusal, a bad key, a malformed request or a budget stop is reported rather than re-sent.
This is also why video generation ships with retries off, and why a tool that reports an error is never retried automatically.
Re-running only what failed
Retry failed on the run re-runs the failed items, keeps the successful ones, and shows the estimated cost before you confirm. You never re-pay for work that already succeeded — and if you had pinned an upstream step, it is not re-paid for either.
When the whole run failed instantly
Usually one of:
- No pool on a step — it ran in free test mode, or refused to start.
- A spend ceiling already reached — a run that cannot possibly spend is refused up front rather than failing item by item.
- No items. A batch with zero rows has nothing to do.
Items marked "Needs review"
Not a failure. A Repeat loop hit its try limit and the item finished with its best attempt, flagged so you look rather than ship it blind.