FLORA MCP runs: polling, timeouts and failures
Follow FLORA MCP runs from start to finish: run statuses, polling a batch with flora_list_generations, Technique runs, how long runs take, stuck runs, and what to do with each error code.
Every generation or Technique your agent starts through FLORA MCP is a run: it gets a run_id right away and finishes in the background. This page covers how to wait for runs without hitting rate limits, how long they take, when to call one stuck, and what each failure code means.
The run lifecycle
flora_create_generations, flora_run_technique, flora_run_canvas_nodes and flora_train_lora return a run_id as soon as the run is accepted. A started generation also returns its node_id, the canvas_url to give the user, a charged_cost estimate and estimated_seconds. The node is on the canvas from the start and fills in when the run finishes.
A run read reports one of four statuses:
status
Meaning
What to do
pending
Accepted and waiting to start (queued for a slot or for the model)
Keep polling at the poll interval
running
The model is working
Keep polling at the poll interval
completed
Finished. outputs holds the results and charged_cost the cost
Show the outputs, or use them in the next step
failed
Finished without a result. error_code and error_message say why. A failed run with no error_code was most likely cancelled by a person in the canvas
Act on the error class
completed and failed are final. A run never changes after that, and a failed run doesn't retry on its own.
Key on status only. For generation runs, progress reads 0 until the run ends and 100 after, for failures too, so it's not a progress bar. Technique runs fill in progress as their steps finish.
Poll a batch
Read every run of a batch in one call. run_ids is an array even for one run:
{
"run_ids": ["run_a1", "run_b2", "run_c3"]
}The response has one entry per ID, in the order you sent them:
Output type is one of imageUrl, videoUrl, audioUrl, text, documentUrl or model3dUrl. Pass an output's asset_id or url to the next step. For 3D results, flora_view_model3d with the run_id opens a viewer.
Why the poll rule exists
Every ID in run_ids is one API request against the per-minute rate limit, which is counted against your credential's default workspace and shared with every agent, API key and script counted there. Polling a 20-run batch every few seconds would use the whole budget on status checks and starve the work itself. So the MCP server enforces the interval:
After a successful read, the same runs can't be read again for
max(15, 2 × number of run_ids)seconds. Reading early returns a cooldown entry withstatus: 429andretry_after_seconds, never cached data.If the API itself rate-limits a read, that run cools down for 60 seconds.
If every ID in a call is cooling down, the whole call fails with
retry_after_seconds. Wait that long.
1 to 7
15 seconds
10
20 seconds
15
30 seconds
20
40 seconds
Make the first poll after the same interval, max(15 s, 2 s × runs): runs can finish earlier than their estimate. For slow models, such as video, it's fine to wait longer (about estimated_seconds) before the first poll to save requests. Agents that can't sleep between calls can tell the user the work is running and check back on the next turn.
Entries that aren't runs
An ID that isn't a run gets its own ok: false entry, and the rest of the batch still reads:
Canvas node IDs, asset IDs and quote entries have no run to read. Only pass the run_id values that flora_create_generations, flora_run_technique, flora_run_canvas_nodes or flora_train_lora returned.
History instead of exact runs
Leave out run_ids to list history, newest first, with optional workspace_id, project_id, status, limit and cursor filters. Add include_inputs: true to get each run's submitted prompt and references. Use history to find runs you lost track of, never as a substitute for reading the IDs you hold.
Technique runs
flora_run_technique returns a run_id too. Poll it with the same tool and pass the Technique's ID:
technique_id applies to every ID in the call, so read Technique runs and plain generation runs in separate calls. A Technique run bills your credential's default workspace, because flora_run_technique takes no workspace_id. To list past Technique runs, use flora_list_technique_runs.
How long runs take
Each model reports estimated_seconds in flora_list_models, and a started generation returns it too. In the catalog today:
Output
Typical estimated_seconds
Image
Most models 20 to 90 seconds. The fastest take about 5 seconds; a few vector models estimate about 8 minutes
Video
Most models 2 to 5 minutes. The slowest take up to about 26 minutes
Audio
5 to 40 seconds
3D
About 5 minutes
Technique
No estimate. See Technique timing
These are estimates, not promises: read estimated_seconds for the model you picked, and expect longer at busy times when the model's queue is long. Runs in one flora_create_generations call start together, so a batch of 20 takes about as long as its slowest item, not 20 times as long.
Technique timing
Techniques don't report estimated_seconds. A Technique runs its steps as model generations, so it takes at least as long as its slowest step, and longer when steps run one after another.
Wait 15 seconds, the minimum poll interval, before the first poll. Then poll at the interval.
For a real estimate, read a recent run of the same Technique with
flora_list_technique_runs(passtechnique_idandstatus: "completed") and compare itsstarted_atandcompleted_at.Technique runs fill in
progressas their steps finish, so a risingprogressmeans the run is moving.FLORA fails a Technique run that hasn't finished after 60 minutes, with
TECHNIQUE_TIMEOUT.
When a run seems stuck
Don't judge a run by elapsed time alone. FLORA ends runs that overrun on its own:
A generation that runs far past its estimate fails with
GENERATION_PROVIDER_TIMEOUT. The deadline is set when the model provider accepts the job: the larger of 7 minutes and 8 ×estimated_seconds, plus half ofestimated_secondsfor every job ahead of it in the provider's queue at that moment. There's no fixed overall cap, so a long provider queue pushes the deadline out.A Technique run fails with
TECHNIQUE_TIMEOUTafter 60 minutes.A run waiting for an account slot (new accounts run one generation at a time) fails with
GENERATION_QUEUE_NOT_MOVINGafter an hour.
A failed run isn't charged, so a run that times out costs nothing.
Stop waiting when a generation is still pending or running after 8 × estimated_seconds (at least 7 minutes), or when a Technique run takes well past what earlier runs of the same Technique took. Then:
Tell the user it's taking longer than expected, and give them the
run_idand thecanvas_url. The node fills in on the canvas as soon as the result lands.Don't start the same request again. The original may still finish and bill, and a second copy bills again.
Check the run again later, or in the next conversation, with
flora_list_generations. FLORA either finishes it or fails it on its own.If a later check still shows it
pendingorrunning, email [email protected] with therun_id, the time you started it, your client and the tool you called.
Cancelling
There's no cancel tool and no cancel endpoint in the API. A person can stop a run from the canvas: open the canvas_url, right-click the running node and choose Cancel generation (see How Nodes Run). That stops a run that hasn't reached the model yet. A run the model provider already accepted keeps going and is still billed; cancelling only keeps its result off the node.
After a timeout, check before you retry
If a create call times out or the conversation drops, the run may have started anyway. flora_create_generations has no idempotency key, so firing again can bill twice. Read history first:
Match the submitted prompts against what you meant to start, and re-fire only what's missing. For Techniques, check flora_list_technique_runs with the technique_id. Two tools do protect against duplicates: reuse the same idempotency_key when you retry flora_add_to_canvas, and the same client_token when you retry flora_train_lora.
Error codes
Failures show up in two places:
At start: a
flora_create_generationsentry withok: false, anerrorand an HTTPstatus. Nothing started and nothing was charged for that entry.On a run: a run read with
status: "failed", anerror_codeand anerror_message. The run's cost was released.
Classify by code, then read error_message before acting. GPU_PROVIDER_ERROR and GENERATION_NO_RESULT often carry a model's safety refusal ("rejected by the safety system", "declined this request"). If the message names safety, moderation, a refusal or a policy, treat it as change the input, whatever the code. Retrying a refusal unchanged fails the same way.
Retry now
Transient. Retry once, as a new run; if it fails the same way again, report it.
GENERATION_PROVIDER_TIMEOUT
The model took too long
GENERATION_FAILED_TO_START, GENERATION_PROVIDER_FAILED_TO_START
The run couldn't start
GENERATION_GENERIC_ERROR, GPU_PROVIDER_ERROR, SERVER_ERROR
Unexpected error during the run (check the message for a refusal)
GENERATION_PREGENERATION_FAILED, GENERATION_POSTGENERATION_FAILED, GENERATION_MAP_AFTER_REQUEST_FAILED
Preparing the input or processing the result failed
GENERATION_FAILED_TO_UPLOAD, GENERATION_FAILED_TO_UPDATE, GENERATION_FAILED_TO_GET
FLORA couldn't save or read the result
TECHNIQUE_GENERATION_FAILED
A step inside a Technique failed
HTTP 500 internal_error or unknown_error
The API failed. Check that the prj_ and ws_ IDs are real first: a malformed ID can surface as a 500
Retry later
The model or provider is overloaded or down. Wait a few minutes before one retry, or switch to another model.
GENERATION_QUEUE_TOO_LARGE
The model is at capacity
GENERATION_QUEUE_NOT_MOVING
The run waited too long to start
GENERATION_DOWNSTREAM_SERVICE_ERROR, GENERATION_CIRCUIT_BREAKER_OPEN
The model provider is having problems
GENERATION_INVALID_PROVIDER_RESPONSE, GENERATION_NO_RESULT
The model returned nothing usable (check the message for a refusal)
GENERATION_MODAL_POLL_ERROR, GENERATION_PROVIDER_FAILED_TO_GET_STATUS
FLORA lost track of the provider's job
AUDIO_GENERATION_ERROR
Audio generation failed at the provider
HTTP 429 rate_limited, or a cooldown entry
Too many requests. Wait retry_after_seconds when it's there. The API's own 429 ("Rate limit exceeded.") has no wait value, so back off about 60 seconds. Then retry reads; don't blindly retry a create, check history first
HTTP 503 temporarily_unavailable
The API is briefly unavailable
Change the input
Retrying the same request fails the same way. Fix the prompt, parameters, model or input first.
GENERATION_PROMPT_MODERATED, LLM_REFUSAL
A safety filter or the model refused the prompt or input. Rephrase or change the input
GENERATION_INPUT_VALIDATION, GENERATION_INVALID_PARAMS
An input or setting doesn't fit this model. Read its params with flora_list_models and model_id
GENERATION_INVALID_URL
An input URL is invalid or unreachable. Upload the file with flora_create_asset
GENERATION_MAP_BEFORE_REQUEST_FAILED
FLORA couldn't prepare the input for this model
GENERATION_ENDPOINT_NOT_FOUND, GENERATION_PROVIDER_NOT_SUPPORTED
The model ID isn't available. Pick one from flora_list_models
TEAMS_WORKSPACE_MODEL_NOT_AVAILABLE, ACCESS_SERVING_PROVIDER_NOT_ALLOWED
The workspace or organization doesn't allow this model. Pick another
LLM_OUTPUT_TRUNCATED
The text model ran out of room. Ask for less
LLM_CANNOT_GENERATE_MEDIA
A text model was asked for an image or video. Use an image or video model
LLM_ERROR
The text model returned an error or no usable answer. Rephrase the request, or pick another text model
TECHNIQUE_NO_OUTPUTS_PRODUCED
No branch of the Technique matched these inputs
HTTP 400 input_validation_error
The request is malformed. The message (and fields) names what to fix
HTTP 404 not_found
An ID is wrong or belongs to another workspace. Look it up with the matching list tool
Report it
Not retryable. Stop and tell the user what happened, quoting the message.
insufficient_credits (HTTP 402), BILLING_*, GENERATION_NOT_PAID
Balance or a spending limit. See When the money runs out. Relay the message and its link; don't retry
ACCESS_*, HTTP 403 forbidden
The user's role or the credential doesn't allow this in this workspace
*_ENTITLEMENT_REQUIRED, HTTP 403 paid_plan_required
The workspace's plan doesn't include what was asked, such as API access or a feature. Adding balance doesn't fix it. Pick a workspace whose plan includes it, or upgrade
HTTP 401 unauthorized or invalid_api_key
Sign-in failed. Reconnect the client (see Troubleshooting)
failed with no error_code, or GENERATION_CANCELLED
Most likely a person cancelled the run in the canvas (a canvas cancel sets no error code). Don't re-run it unless the user asks
TECHNIQUE_NODE_CONFIG_ERROR, TECHNIQUE_GRAPH_STUCK, TECHNIQUE_GRAPH_CYCLE
The Technique itself is broken. Tell its owner
TECHNIQUE_TIMEOUT
The Technique ran for 60 minutes without finishing
A retry now code that failed twice
Send the run_id to support
Related
Last updated
Was this helpful?