> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trace-db.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trace-db.com/_mcp/server.

# Idempotency and Retries

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.