Retry a failed run

POST /runs/{runId}/retry needs workflowBuilder.

What this endpoint does

Queues a failed run of a deployed workflow to execute again. A retry is not a resume: the whole workflow runs from the trigger again, including steps that already succeeded, paid rewards, or called an outside service.

There is no confirmation header and no separate retry permission to hold back a caller who should not retry: workflowBuilder covers it. What protects you is the per-run claim below, which stops two retries of one run from both queueing, and an Idempotency-Key, which turns a lost response into a replay.

Quick start

Authentication and permission

Authorization: Bearer <API_KEY> with workflowBuilder, and the run must belong to the key's community.

Failure	Meaning	Recovery
`403 API_KEY_PERMISSION_DENIED`	The key has no `workflowBuilder` permission	Grant the permission.
`404 RUN_NOT_FOUND`	Unknown run id, or a run of another community	Use a run id from the list.
`409 RETRY_IN_PROGRESS`	A retry of this run is already claimed, and this call carried no key or a different one	Wait for the queued retry to finish, then read the runs list.

Complete examples

A first call queues the run:

{
  "data": {
    "requested": 1,
    "queued": 1,
    "skipped": [],
    "sideEffects": "real",
    "alreadyRequested": false,
    "reExecution": "The whole workflow runs again from the trigger, including steps that already succeeded, paid rewards or called outside services."
  }
}

A repeat with the same Idempotency-Key replays the recorded answer instead of queueing again:

{
  "data": {
    "requested": 1,
    "queued": 1,
    "skipped": [],
    "sideEffects": "real",
    "alreadyRequested": true,
    "reExecution": "The whole workflow runs again from the trigger, including steps that already succeeded, paid rewards or called outside services."
  }
}

A second call while the first retry is still in progress, with a different key or no key, is refused:

{
  "meta": {
    "status": "error",
    "statusCode": 409,
    "code": "RETRY_IN_PROGRESS",
    "runId": "65f1a2b3c4d5e6f708192a45",
    "requestId": "3f4d0e8b-7a6c-4f1e-9b2d-5a7c8e1f0a3b"
  },
  "message": "API request rejected error.",
  "detail": "A retry for this run is already in progress. Wait for it to finish before retrying again.",
  "solution": "Read error detail and try again."
}

Success and readback

HTTP 200 with requested, queued, skipped, sideEffects, alreadyRequested and reExecution.

queued: 1 with alreadyRequested: false means a retry was accepted. Read back with GET /{workflowId}/runs: a new run appears with its own id, and the original run keeps its result.

alreadyRequested: true means the platform replayed the answer it recorded for this run and this Idempotency-Key. The body is the original answer, so queued: 1 describes the first call rather than this one. A replay is served for 24 hours, whether or not the ten-minute claim is still held.

sideEffects: "real" is always present. A retry is a real execution.

Errors and recovery

Status and code	When	Recovery
`401 AUTHENTICATION_REQUIRED`	No key, or an unknown key	Send a valid key.
`403 API_KEY_PERMISSION_DENIED`	The key has no `workflowBuilder` permission	Grant the permission.
`404 RUN_NOT_FOUND`	Unknown run id, or a run of another community	Use a run id from the list.
`409 RETRY_IN_PROGRESS`	A retry of this run is already claimed, and the call carried no key or a different key	Wait for the queued retry to finish, then read the runs list.
`429 RATE_LIMITED`	The community's API rate limit was reached	Wait for the window to reset, then retry.
`500 INTERNAL_ERROR`	Unexpected failure	Read the runs list before retrying: the retry may already be queued.

Retry safety

This is the one call in the family whose whole point is a controlled repeat, so its own retry behaviour matters. Two guards run in this order:

A recorded answer for your key is checked first. If this run already accepted a retry under your Idempotency-Key, the platform returns that answer with alreadyRequested: true and queues nothing. The record lasts 24 hours, so a client that retries after a timeout still cannot queue a second re-run, even long after the first claim expired.

Otherwise a claim is taken on the run and its current state. While that claim is held, a call with no key or a different key is refused with 409 RETRY_IN_PROGRESS and queues nothing. Two retries of one failed run can therefore never both queue.

The claim lasts ten minutes. After it expires, a call with a new key or no key takes a new claim and queues a new re-run: the workflow really executes again, so a reward step can pay twice. Only the same key is protected, and only by the 24-hour record.

If queueing itself fails, the claim is released, so a failed attempt does not block a legitimate retry. Use an Idempotency-Key on every retry: it is what turns a lost response into a replay instead of a refusal.

Gotchas

A retry runs the whole workflow again. It does not continue from the failed step, so a step that already paid a reward runs again and may pay again.

Only a failed run of a workflow that is currently deployed is queued. Anything else is skipped with queued: 0 and a reason in skipped, including a run that succeeded, a run that is still in progress, and a workflow that is no longer deployed.

A retry runs the workflow's current deployed steps with the failed run's recorded trigger output. It is the same event as far as the steps are concerned, against the configuration as it is now, so a step you changed after the failure runs in its new form.

The response describes the request, not the result. Read the runs list for the outcome.

There is no dry run of a retry: it is a real execution by definition, and the response says sideEffects: "real" on every answer. If you want to know what the retry will do, dry-run the workflow (POST /{workflowId}/test with mode: "dry-run") before queueing it.

Next steps

GET /{workflowId}/runs to confirm a new run appears.

GET /runs/{runId} on the new run for its step results.

PATCH /{workflowId}/nodes/{nodeId} to fix the step that failed before retrying again.

Responses

🟢200200 Success

application/json

Whether a retry was queued.

Bodyapplication/json

🟠400400 VALIDATION_FAILED

🟠401401 AUTHENTICATION_REQUIRED / API_KEY_REQUIRED

🟠403403 API_KEY_PERMISSION_DENIED

🟠404404 RUN_NOT_FOUND

🟠409409 RETRY_IN_PROGRESS

🟠429429 RATE_LIMITED

🔴500500 INTERNAL_ERROR

curl --location --request POST 'https://api.returning.ai/v1/workflow-builder/data-workflows/runs/65f1a2b3c4d5e6f708192a40/retry' \ --header 'Authorization: Bearer <API_KEY>' \ --header 'Idempotency-Key: create-vip-bonus-001'

{ "data": { "requested": 1, "queued": 1, "skipped": [], "sideEffects": "real", "alreadyRequested": false, "reExecution": "The whole workflow runs again from the trigger, including steps that already succeeded, paid rewards or called outside services." } }

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request