checkpoint_pending: The stream waits for its next checkpoint
When between a quarter and a tenth of a budget is left, a stream on default protections that has unsettled work of its own takes its next request only after that work is checkpointed. The scheduler's next engine pass does it; the same request is then admitted.
What to do
- Nothing, if you use an SDK:
@dynamoprotocol/sdk3.0,dynamoprotocol0.3.0 and the OpenAI Agents plugin wait for the pass and retry the same request for you (30 seconds at most by default). - Otherwise wait for the
Retry-Afterheader (seconds) orretry_after_ms, then send the same request again. Retrying with the samerequestRefis safe: it is billed at most once. - To get the refusal at once instead, set
checkpointWaitMs: 0(TypeScript) orcheckpoint_wait_seconds=0(Python).
On the wire
HTTP 409, error type halted, and a Retry-After header on every route.
Without Dynamo-Error-Detail: 1 the body is the earlier exposure refusal, unchanged, with no errorDetail and so no retry_after_ms; the Retry-After header is still sent. The payment authorization and receipt routes and the test-fixture run route (POST /owner/v1/test-fixtures/streams/{id}/run) send the detailed body to every client. With the header:
{
"error": "halted",
"reason": "exposure",
"streamId": "stm_…",
"detail": "…",
"errorDetail": {
"type": "halted",
"code": "checkpoint_pending",
"message": "…",
"param": null,
"doc_url": "…/errors/checkpoint_pending.md",
"fix": "the stream waits for its next checkpoint; retry the same request after Retry-After (the SDKs wait for you)",
"retry_after_ms": 15000
}
}
See all error codes.