For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Polling rule. Save every run_id. Wait at least 15 seconds between polls, or 2 seconds per run for bigger batches (40 seconds for 20 runs). Then read every run_id in one flora_list_generations call (up to 20 per call). For example: flora_list_generations({"run_ids": ["run_a", "run_b"]}). For Technique runs, also pass "technique_id". Polling faster returns 429 or cooldown errors with retry_after_seconds.

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 with status: 429 and retry_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.

Runs in the batch
Wait between polls

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 (pass technique_id and status: "completed") and compare its started_at and completed_at.

  • Technique runs fill in progress as their steps finish, so a rising progress means 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 of estimated_seconds for 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_TIMEOUT after 60 minutes.

  • A run waiting for an account slot (new accounts run one generation at a time) fails with GENERATION_QUEUE_NOT_MOVING after 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:

  1. Tell the user it's taking longer than expected, and give them the run_id and the canvas_url. The node fills in on the canvas as soon as the result lands.

  2. Don't start the same request again. The original may still finish and bill, and a second copy bills again.

  3. Check the run again later, or in the next conversation, with flora_list_generations. FLORA either finishes it or fails it on its own.

  4. If a later check still shows it pending or running, email [email protected] with the run_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_generations entry with ok: false, an error and an HTTP status. Nothing started and nothing was charged for that entry.

  • On a run: a run read with status: "failed", an error_code and an error_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.

Code
Meaning

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.

Code
Meaning

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.

Code
Meaning

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.

Code
Meaning

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

Last updated

Was this helpful?