All glossary terms

Serving

Idempotency

Designing requests so a retry cannot bill twice or answer twice, because a provider retry re-bills the whole request at full prompt and output price.

A timeout is ambiguous: the request may have failed to leave, failed mid-flight, or completed while the answer was lost on the way back. Retrying is the only recovery, and a retry that the provider cannot tell apart from the original runs the work again and bills it again. Idempotency is the design that removes the ambiguity: a unique key sent with the request, and the provider deduplicates on it by returning the first result for a repeated key instead of running the work twice.

In model serving, the retry economics are unusually harsh because retries are whole-request events. A re-issued request re-sends the full prompt, re-bills prompt and output at full price, and reports itself as brand new traffic everywhere but the meter. Agent-style products, where requests are long and timeouts are likeliest, spend their retry budget on the most expensive requests they have.

The design moves are ordinary but they are deliberate. Send an idempotency key on every state-changing or billable call, and cache completed results against it so a retransmission replays instead of re-runs. Treat key handling as part of the client contract: the same retry may reach two instances, and the dedupe has to survive that. Meter the retried share separately, because the gap between requests the product counted and requests the bill counted is exactly the share the retry design was supposed to make visible.

A worked example

A research-agent request moves 12,000 input tokens and 4,000 output tokens on the flagship tier, at $3 and $15 per million tokens. A timeout hits 8 percent of runs, and each timeout re-issues the whole request once.

  1. One clean request: 12,000 x $3 / 1,000,000 = $0.036 of prompt, 4,000 x $15 / 1,000,000 = $0.06 of output, $0.096 in total.
  2. A retry re-bills the whole request, not the tail: with 8 percent of runs retried once, the expected bill per issued request is 0.096 x 1.08 = about $0.104.
  3. A successful deduplication turns that re-billed $0.096 into a $0 replay of a cached result - the gap between retrying and resuming.

One retried agent request in twelve moves the expected bill from $0.096 to about $0.104, all of it prompt and output re-billed - which is the cost idempotency keys exist to prevent.

Where this shows up

Test yourself

Related terms