What happened
A wallet signs one payout at a time. This payout waited behind other in-flight payouts on the same wallet and timed out in the signing queue before it could start collecting signatures. No funds were moved. The payout is in a terminal failed state withfailureCode: user_signature_timeout.
This is a queue-wait failure, not a signing-window failure. The payout never reached the signing step, so no transaction.awaiting_signature webhook was sent for it. If instead your signer was asked to approve (you received transaction.awaiting_signature) but the signing window closed before the roster signed, the code is user_signature_expired, not this one.
Common causes
- Too many payouts on one wallet at once — a wallet signs one payout at a time, so payouts submitted together queue behind each other on the same wallet.
- An earlier payout held the wallet for its full signing window — while one payout waits for its signers, the payouts queued behind it can age out of the queue before they ever reach the signing step.
Recovery
1. Confirm the terminal statePrevention
- Limit concurrent payouts per wallet — submit the next payout on a wallet after the previous one has cleared the signing step, rather than many at once, so payouts do not stack up in the queue.
- Handle
transaction.failedwith this code — branch onfailureCode === 'user_signature_timeout'to resubmit once the wallet’s earlier payouts have finished signing.
Related webhooks
Thetransaction.failed event fires when the payout times out in the queue:
Related endpoints
- GET /v2/payouts/:id — read payout state
- POST /v2/payouts — submit a new payout