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.

​
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
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:
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:
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":

​
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