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.
  • An onramp or offramp receiving outcome: "completed" on simulate/terminal before its delivery has completed. A conversion cannot report success until the funds have actually been delivered to the destination; in sandbox the delivery completes on its own within seconds of the source funds settling.

​
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
  • Requesting completed before an onramp/offramp has delivered — on simulate/terminal, a conversion accepts outcome: "completed" only once the funds have reached the destination. Fund the order (and clear any pending step, such as a signature), wait a few seconds, or use outcome: "failed" to exit early
  • 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 does not return this 422. It returns 200 with the transaction at its actual terminal state, and it does not disturb settlement work still finishing (such as fee collection).

​
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