Need help - Building a error retry flow for a multi instance flow and using token to retry errors on a multi instance flow

Integrator.io
1

Building a error retry flow for a multi instance flow and using token to retry errors on a multi instance flow.

I have been trying to find a proper documentation on this but no luck so far.

2

Multi-instance flows are just regular flows that inherit from an abstract flow. Each instance has its own flow ID, so the error retry workflow is the same as any other flow — you just need to find the right instance first.

Full API reference for all of these endpoints: Flows API

Step 1: Find the instance flow IDs

The abstract flow is the "parent" you see in the UI. List its instances by filtering on _abstractFlowId:

GET /v1/flows?_abstractFlowId={abstractFlowId}

Each item in the response is a regular flow with its own _id — that's the flow ID you use for everything below.

Step 2: Find the step ID

The "step ID" is the export or import ID within the flow where the error occurred. Instances share the same step IDs as their abstract flow — they don't get their own copies.

The quickest way to find steps with errors is the flow-level error summary:

GET /v1/flows/{instanceFlowId}/errors

Response:

{
  "flowErrors": [
    { "_expOrImpId": "6a0fc7eb7202049b32ea45b5", "numError": 0 },
    { "_expOrImpId": "6a0fcdfa3f8562a7b1a3b3f2", "numError": 1, "lastErrorAt": "2026-05-22T04:22:12.852Z" }
  ]
}

The _expOrImpId with numError > 0 is your step ID.

You can also get the full list of step IDs from the abstract flow's pageGenerators[]._exportId and routers[].branches[].pageProcessors[]._exportId/._importId. Or use mergeInstance=true on the instance GET to see the merged config:

GET /v1/flows/{instanceFlowId}?mergeInstance=true

Without mergeInstance=true, instance flows return a sparse object — just _abstractFlowId, overrides, and instance-level fields, with no pageGenerators or routers.

Step 3: Get the errors and retry

List the open errors on that step:

GET /v1/flows/{instanceFlowId}/{stepId}/errors

Each error with a retryDataKey is retryable. Collect the keys and post them to retry:

POST /v1/flows/{instanceFlowId}/{stepId}/retry
Content-Type: application/json

{
  "retryDataKeys": ["fad632cf388547f9a0d73a4b54d34f8d"]
}

This returns a type: "retry" job. The original error moves to resolved automatically. If the retry still fails, a new error is created with the same retryDataKey but a new errorId.