> ## Documentation Index
> Fetch the complete documentation index at: https://v2.docs.conduit.financial/llms.txt
> Use this file to discover all available pages before exploring further.

# SANDBOX_TRANSACTION_NOT_FORCE_TERMINAL_READY error

> A sandbox simulate endpoint was called with an outcome that is not valid in the transaction's current phase

## What happened

A sandbox simulate endpoint refused the request because the requested outcome is not viable in the transaction's current phase. This returns HTTP 422 with error code `SANDBOX_TRANSACTION_NOT_FORCE_TERMINAL_READY`. Three endpoints return this code today: `POST /v2/sandbox/transactions/{id}/simulate/terminal`, `POST /v2/sandbox/payouts/{id}/simulate/settled`, and `POST /v2/sandbox/payouts/{id}/simulate/confirm`.

The most common cases:

* A fiat payout with no selected settlement route receiving `outcome: "completed"` on `simulate/terminal`. The `completed` path requires the payout to be in the settlement-ready phase; before that, only `outcome: "failed"` is accepted.
* A payout that carries supporting `documents` (any `purpose` other than `intercompany`) parks at the document-review gate before broadcast / settlement. Calling `simulate/settled` (fiat) or `simulate/confirm` (crypto) while the gate is still open used to silently 200 with no observable effect; Conduit only acts on the settlement / chain-confirm call after the gate clears. The 422 now surfaces the gap explicitly.

```json theme={null}
{
  "type": "SANDBOX_TRANSACTION_NOT_FORCE_TERMINAL_READY",
  "title": "Transaction Not Force-Terminal Ready",
  "status": 422,
  "detail": "The requested terminal outcome is not viable in the transaction's current phase.",
  "resolution": "Wait for the transaction to advance to the next phase, or use outcome: 'failed' to terminate from the current phase.",
  "docs": "/errors#sandbox-transaction-not-force-terminal-ready",
  "instance": "/v2/sandbox/transactions/txn_abc123/simulate/terminal",
  "correlationId": "corr_xyz789",
  "timestamp": "2026-01-15T09:30:00.000Z"
}
```

## Common causes

* **Payout parked at the document-review gate** -- the payout carries `documents` and is waiting for `simulate-review-approve` / `simulate-review-reject` before it can advance to broadcast / settlement. `simulate/settled` and `simulate/confirm` return 422 in this state.
* **Requesting `completed` too early on a fiat payout** -- on `simulate/terminal`, a fiat payout must have a settlement route before `outcome: "completed"` is accepted; route selection runs automatically after the compliance phase clears
* **Unsupported phase** -- the transaction is in a phase that the force-terminal endpoint does not support for the requested outcome

Note: a call against a transaction that has *already* reached a terminal state returns `RESOURCE_TERMINAL` (409), not this 422. See the [RESOURCE\_TERMINAL playbook](/errors/resource-terminal).

## Recovery

**1. Re-fetch the transaction to check the current phase**

```bash theme={null}
curl -X GET https://api.sandbox.conduit.financial/v2/transactions/txn_abc123 \
  -H "x-api-key: YOUR_API_KEY"
```

Check the `status` and `waitingOn` fields to understand what phase the transaction is in.

**2. Clear the document-review gate first if your payout carries `documents`**

If the 422 came from `simulate/settled` or `simulate/confirm`, the payout is most likely parked at document review. Approve (or reject) the review before retrying the terminal lever:

```bash theme={null}
curl -X POST https://api.sandbox.conduit.financial/v2/sandbox/payouts/txn_abc123/simulate-review-approve \
  -H "x-api-key: YOUR_API_KEY"
```

`simulate-review-reject` instead terminates the payout as `failed` with `failureCode: compliance_rejected` and returns the reserved funds. See [withdrawals](/sandbox/withdrawals) for the full flow.

**3. Use `outcome: "failed"` to terminate immediately**

If you need to terminate the transaction from its current phase without waiting, use `outcome: "failed"` on `simulate/terminal`:

```bash theme={null}
curl -X POST https://api.sandbox.conduit.financial/v2/sandbox/transactions/txn_abc123/simulate/terminal \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "failed"}'
```

**4. Wait for the phase to advance, then retry `outcome: "completed"`**

For fiat payouts on `simulate/terminal`, wait a few seconds for route selection to run, then retry with `outcome: "completed"`:

```bash theme={null}
curl -X POST https://api.sandbox.conduit.financial/v2/sandbox/transactions/txn_abc123/simulate/terminal \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "completed", "utr": "sandbox-settlement-ref"}'
```

## Prevention

* **Approve document review before settlement** -- a payout that carries `documents` parks for review before it can settle / confirm. Call `simulate-review-approve` first.
* **Understand phase gating** -- fiat payouts require route selection before the `completed` path opens on `simulate/terminal`; deposits require the compliance phase to clear
* **Default to `outcome: "failed"` for speed** -- `failed` terminates a transaction from any non-terminal phase; use `completed` only when the happy path is what you need to test
* **Consult the simulate reference** -- the [sandbox cheat sheet](/sandbox/cheat-sheet#simulate-endpoints) documents which outcomes are valid per transaction type and phase

## Related endpoints

* [GET /v2/transactions/{id}](/api-reference/transactions/get-a-transaction-by-id) -- read transaction state and current phase
* [POST /v2/sandbox/transactions/{id}/simulate/terminal](/sandbox/cheat-sheet) -- force a transaction to a terminal state
* [POST /v2/sandbox/payouts/{id}/simulate-review-approve](/sandbox/cheat-sheet) -- clear the document-review gate