settlement_pending: The voucher waits for the chain's clock
A stablecoin (contract v1 or v2) voucher is signed with the core's clock. When the chain has produced no block since then, its latest block time is still earlier than the voucher's signedAt, and the vault refuses a voucher signed after the block that settles it. The core reads the latest block's time first and sends nothing until the chain passes signedAt: nothing was sent, and nothing is lost.
- A forced checkpoint (
POST /owner/v1/streams/{id}/checkpointwithforce: true) waits up to 6 seconds for the chain, then answers this code. - A tick or a reservation confirm still answers 200 (the work is signed and billed); its
checkpointisnull, and the scheduler settles the voucher once the chain passes it. - A revoke still answers 200 and cuts off at once: nothing more is signed. The vault revoke is held until the chain passes the last voucher, so that voucher stays settleable in the grace window; the scheduler sends it then.
- A budget close answers this code while such a vault revoke is held.
What to do
- Wait for the
Retry-Afterheader (seconds) orretry_after_ms, then send the same request again; or leave it to the scheduler, which settles and revokes on its next passes. - On a quiet test network the chain may take minutes to produce its next block. If this answer does not clear, report it with the stream id.
On the wire
HTTP 409 with a Retry-After header. Without Dynamo-Error-Detail: 1 the body is { "error": "state", "reason": "settlement_pending", "detail": "…" }. With the header:
{
"error": "state",
"reason": "settlement_pending",
"detail": "…",
"errorDetail": {
"type": "state_error",
"code": "settlement_pending",
"message": "…",
"param": null,
"doc_url": "…/errors/settlement_pending.md",
"fix": "the voucher was signed after the chain's latest block time and the vault refuses it until the chain's clock passes it; nothing was sent and nothing is lost: retry after Retry-After, or let the scheduler settle it",
"retry_after_ms": 61000
}
}
See all error codes.