Idempotency and Retries | TraceDB Documentation

Read-only routes may use safe retries for transient failures. Mutation, admin, and polymorphic routes require a caller-provided Idempotency-Key before idempotency retries are allowed.

Retry Classes

Retry class	Allowed on	Requirement
Safe retry	Read-only routes	Route is marked read-only by the contract
Idempotency retry	Mutation, admin, and polymorphic routes	Non-empty `Idempotency-Key` with no CR/LF
No retry	Non-idempotent writes without a key	Caller must retry manually if appropriate

SDKs should reject empty or CR/LF-containing idempotency keys before network I/O. safe_retries alone must never retry a mutating request.

Replay Rule

Same Idempotency-Key, same HTTP method, same path, same raw request body, and same actor/routing context replays the first successful response.

If the same key is reused with a different body, TraceDB returns 409 Conflict with code IDEMPOTENCY_CONFLICT.

Durability Boundary

The v0 idempotency authority is local-engine scoped. Replay survives a clean engine reopen from the same data directory. It is not a cross-replica, managed-cloud exactly-once, or crash-atomic exactly-once guarantee.

TraceQL and native GraphQL are polymorphic. SDKs may retry them without an idempotency key only when the payload is provably read-only; otherwise use Idempotency-Key.

For v0.1.1 raw generated clients, do not assume generated transport retries are route-aware. Set retry counts such as maxRetries / max_retries to 0 for write/admin calls unless the language wrapper README documents route-aware idempotency behavior for that call.