Guides

Idempotency

A network retry must not become a second label.

Required write header

All POSTs except quotes require Idempotency-Key. Use 8–128 ASCII letters, digits, underscore, dot, colon or hyphen. Generate and durably save one key per intended operation. The namespace is account + environment + method + path, shared across keys belonging to the same account.

Replay behaviour

The sandbox atomically reserves the key and canonical JSON fingerprint before execution. Reordered object properties are equivalent; array order and values matter. A concurrent identical request returns 409 request_in_progress. An identical completed request returns its original status and body plus Idempotency-Replayed: true. X-Request-ID is new for every attempt; replayed error bodies receive that new request ID. A different body under the same key returns 409 idempotency_conflict.

Durable retention

Reservations and results survive sandbox process restarts and remain until the operator resets the local database. Validation and provider failures after reservation are cached. Fixing a rejected schema requires a new key; an unconfirmed provider operation requires reconciliation first. Unfinished reservations remain in_progress and cannot be blindly re-executed.

Live purchase protection

The disabled server facade now uses a shared Postgres unique reservation and stored response, with the existing provider purchase fence. Pending records never expire into another execution. Independent database-session concurrency and crash recovery still need certification, and no billing authority or hosted test provider is installed. The local SQLite store is single-host and cannot be used on serverless production instances. Live retention and recovery policy must be enforced before publication.