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. Conduit only acts on a terminal-driving call after the gate clears, so simulate/terminal, simulate/settled (fiat) and simulate/confirm (crypto) all return 422 while the gate is still open.
  • 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.
  • A payout in an in-progress phase with no transfer reference the simulation can safely drive yet. simulate/terminal and simulate/confirm refuse rather than act on a step that may be moving money. Retry the same call. A payout that keeps refusing needs a read of the transaction for its current state rather than an indefinite retry.

​
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/terminal, 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
  • Calling while a step is in progress with no reference yet — the payout has an in-progress step that carries no transfer reference the simulation can drive. simulate/terminal and simulate/confirm refuse rather than act on money that may be moving. Retry the same call; a payout that keeps refusing needs a read of the transaction instead of an indefinite retry
  • 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/terminal, 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. Clear the document-review gate first if the payout carries documents — while that gate is open both outcomes are refused:
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 except an open document-review gate; 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