Skip to content

Errors and limits

Every error is a JSON object with an error message. Some add a code you can branch on, and a few add details.

{"error": "Rate limit exceeded for this workspace.", "code": "workspace_rate_limited"}

Branch on the HTTP status and code. Show error to people, but do not parse it: the wording can change.

Authentication errors

Status error What to do
401 Unauthorized The key is missing, mistyped, revoked or expired. Check the x-api-key header, or create a new key.
403 API key is not scoped for this request The key lacks a scope. The response names it in required, for example executions:write, and suggests a fix in hint. Create a key with that scope.
403 This endpoint requires an interactive session, not an API key The endpoint is closed to API keys. Do it in the app. See What a key can never do.
403 This API key is bound to a different workspace The key belongs to another workspace than the workspaceId in the request.
403 Other messages The key's owner does not have permission for this action or workspace.

A key that authenticates but is refused always gets 403, never 401. Retrying with the same key will not help.

Errors when starting a run

These come from POST /api/workflows/{id}/execute.

Status code Meaning What to do
400 executionMode is not one of normal, test, debug, sandbox Fix the body
404 No workflow with that ID, or you cannot see it Check the ID and the key owner's access
409 NO_ACTIVE_VERSION The workflow has never been saved Save it in the editor, then retry
413 workspace_over_quota The workspace is over its storage quota Ask an admin to raise the quota or free space
429 workspace_rate_limited The workspace started too many runs too quickly Wait for the time in the Retry-After header, then retry
503 write_circuit_open Flero is temporarily refusing new runs to protect storage Retry later. Tell your admin if it persists.
503 The run was created but could not be queued The response includes the executionId, marked failed. Retry the request.

Rate limits

Workspaces have no execution rate limit unless an administrator sets one. When a limit is set, runs started in the editor, through the API and by schedules all count toward it, and execute answers 429 once it is reached.

Back off and retry after the number of seconds in Retry-After.

Retrying safely

Status Retry?
400, 401, 403, 404, 409, 413, 422 No. Fix the cause first.
429 Yes, after Retry-After
503 Yes, with a growing delay between attempts
500 Yes, a few times. Contact support if it continues.

execute is not idempotent. Each successful call starts a new run. If a request times out on your side, list recent runs before you retry, so you do not start the same work twice.

Found something out of date? This page lives in the Flero docs content set.