Skip to main content

​
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.
{
  "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.

​
Recovery

1. Re-fetch the transaction to check the current phase 
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: 
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 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: 
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": 
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 documents which outcomes are valid per transaction type and phase