The execution lifecycle

An execution is asynchronous from the first millisecond: the call that starts it answers 202 and hands you an execution_id, and the work happens behind that. Everything on this page answers the question that follows — where is it now, and what do I do about it?

Three fields, three different questions

This is the part worth reading slowly, because the three are easy to confuse and they do not mean the same thing.

Plus one convenience field that sits above all of them:

{
  "is_closed": true,
  "status_code": "PARTIAL",
  "status_reason": "PARTIAL",
  "authentication_status": "AUTH_OK"
}

The ten families

   ACCEPTED ─▶ WAITING ─▶ RUNNING ─┬─▶ COMPLETED · PARTIAL · FAILED
                                   │
                                   ├─▶ ACTION_REQUIRED ─▶ (you answer) ─▶ RUNNING
                                   │                   └─▶ ABORTED  (nobody answered in time)
                                   │
                                   └─▶ AUTH_ERROR · UNHANDLED_AUTH_ERROR
                                       CONFIGURATION_ERROR · TEMPORARY_ERROR · ABORTED

Every reason, by family

Each heading below is a status_code — one of the ten families in the table above — and the rows under it are the status_reason values that belong to it. That is the relationship in one sentence: the family is the situation, the reason is the granular cause.

So a state reading status_code: AUTH_ERROR will always carry one of the reasons in the AUTH_ERROR section, and never a reason from another one. If your integration only handles the ten families it will work; it will just be less specific than it could be, and the failures are exactly where that specificity is worth having.

status_code: ONGOING — it is working

status_code: ACTION_REQUIRED — it is waiting for you

Both publish a form_schema describing exactly what to collect. See Challenges & MFA.

status_code: AUTH_ERROR — we could not get in

The most actionable family, because almost every value here means a person has to do something, and none of them is fixed by retrying.

UNHANDLED_AUTH_ERROR is its own family, not a member of this one, and it has a single reason of the same name: the login failed in a way the engine could not classify. Treat it as transient, and if the same access keeps producing it, send us the execution_id.

status_code: CONFIGURATION_ERROR — the request was not valid

The state carries configurations_errors and parameters_errors naming the offending fields, which is where to look before changing anything.

status_code: ABORTED — it was cancelled

status_code: TEMPORARY_ERROR — try again later

Nothing in this family means your request was wrong. A sensible retry — minutes for the setup ones, longer for OUT_OF_SERVICE — is the right response, with a cap so a source that is down all day does not become an infinite loop.

status_code: COMPLETED · PARTIAL · FAILED

One reason each, carrying the same name as its family — COMPLETED, PARTIAL, FAILED. When the run ends well there is nothing more to say at this level; the detail lives one level down, in the features.

The fourth axis: authentication_status

Reported separately from everything above, and it answers a question the execution status cannot: did we get into the source?

The distinction is the one that decides what you do next:

• We could not get in → a conversation with your customer. Their credentials, their bank, their action.
• We got in and the extraction fell short (PARTIAL, FAILED, TEMPORARY_ERROR after AUTH_OK) → nothing to ask anyone. Retry later, or take what arrived.

The auth_ended webhook delivers this the moment it is known, which is usually well before the execution ends — that is what lets you start the “ask for the credentials again” conversation early.

One level down: the features

features carries one entry per feature you requested, each with its own status_reason from a parallel vocabulary. This is where a PARTIAL explains itself.

A results endpoint for a feature that never finished answers 202; one for a feature you never requested answers 204. Both are described in Reading the results.

How to follow one

An engine talks to a real institution over a real network: seconds to minutes is normal, and a source that produces its report on its own schedule can take considerably longer. Size your own timeouts on the slowest feature you requested, not on the average.

The clocks

Three timings come back on the state, and they answer three different questions:

And three limits end an execution on their own:

• execution_timeout — active processing, 60 to 1200 seconds, chosen per execution (default 1200). Waiting for you does not count against it.
• action_required_expires — the deadline to answer a challenge. Past it, ABORTED / ACTION_TIMEOUT.
• The unattended window — an execution started with customer_interaction_available: false has up to three hours to find a moment when the source cooperates, then gives up.

Running the same engine twice

An application cannot have two live executions for the same customer and engine — nor two carrying the same external_execution_id for the same customer, nor two on the same token. The second is refused with 409, and the body names the one already running so you can follow it instead of guessing. It is a guard against a double-submitted form running two logins against a bank at the same time, which some institutions treat as an attack.

If the parallel run is deliberate, give each one a different external_execution_id: your own identifier makes them distinguishable and both are accepted. It travels through every event and every state, which also makes it the natural place for your case number.

Ending it yourself