Idempotency becomes important the moment a Claude-powered workflow can be retried. A network timeout, worker restart, queue redelivery, or user double-submit can cause the same logical job to reach the application more than once. If the workflow only generates text, that may produce duplicate cost or duplicate output. If the workflow can call tools that change external systems, the same ambiguity can create duplicate tickets, repeated notifications, duplicate transactions, or conflicting updates.
The safest starting point is not to assume the model API will deduplicate ordinary message creation for you. Anthropic’s current Messages API documentation does not describe a general idempotency-key contract for normal message creation. Some endpoints are explicitly described as idempotent—for example, reading the status of a Message Batch—but that is not the same as a guarantee that repeating a message-creation request is deduplicated. Application-level idempotency therefore belongs in the architecture around the call.
This is a broader Claude engineering issue rather than a Claude-only quirk. Distributed systems regularly face the difference between “the request failed” and “the caller did not learn whether it succeeded.” Good designs make that uncertainty explicit.
Define the logical operation before defining the retry
An HTTP request is not always the unit that should be deduplicated. The useful unit is the business operation: summarize document version 42, classify ticket 781, generate the approved release note for commit abc123, or process invoice event evt_456. Each of those operations can be assigned a stable application key that remains the same across transport retries and worker redeliveries.
That key should be created before the Claude call and stored in durable state. A simple record can track states such as pending, running, completed, and failed, together with the input fingerprint and resulting artifact. When another worker receives the same operation key, it can determine whether to wait, return the existing result, resume recovery, or reject a conflicting request. The model does not need to know any of this unless the identifier is useful for tool calls or logging.
The input fingerprint matters because a reused key with different content is dangerous. If the same operation identifier arrives with a different prompt, document revision, model policy, or requested action, the system should treat that as a conflict rather than silently returning an unrelated cached result. Idempotency is about making repeats safe, not about hiding inconsistent callers.
Distinguish duplicate model work from duplicate side effects
A duplicate Claude response is usually inconvenient; a duplicate external action can be harmful. This is why tool-level idempotency deserves stricter treatment than model-call deduplication. When an agent can create or mutate resources, each side-effecting tool should accept a stable operation identifier where the downstream system supports it, or the integration should maintain its own deduplication record.
Consider an agent that creates an incident after diagnosing a failed service. The model may decide to call create_incident and the ticketing system may accept the request, but the worker can crash before the tool result is persisted. On restart, the agent no longer knows whether the ticket exists. If the tool can query by the original operation key, the application can reconcile state before creating anything again. Without that mechanism, retrying the entire turn can produce a second incident.
This is also why a sound tool-use contract returns durable identifiers. A tool result that includes the created resource ID, version, and current state gives the next loop enough evidence to avoid guessing.
Timeouts create ambiguity even when the server did real work
The hardest failure is not a clear 400 or 500. It is a lost response. The client sends a request, waits, and then the connection breaks. The server may have rejected the request, may still be processing it, or may have completed it successfully while the response was lost. From the caller’s point of view, those states can look identical.
If the application simply resends the same model request, it accepts the possibility of paying for and processing the work twice. That may be acceptable for a low-cost stateless classification. It may be unacceptable for an expensive long-context analysis or an agent turn that triggers side effects. The retry policy should therefore be based on the cost and consequences of duplicate work.
For expensive operations, one useful pattern is a durable job layer around Claude. The client submits a logical job once, receives an application job ID, and polls or streams the job’s state. The worker can make API attempts internally, but the caller interacts with the stable job record rather than the individual model request. This separates user retries from model retries.
Message Batches provide correlation, not a universal deduplication key
Anthropic’s Message Batches API requires each request inside a batch to have a unique custom_id. That identifier is valuable because batch results can be returned out of order; the application can match each result to its original request. A failed individual request also does not cause the rest of the batch to fail.
The custom_id should not be mistaken for a global exactly-once guarantee across independently submitted batches. Its documented role is to identify requests within the batch. If an application resubmits the same business dataset as a new batch, it should still use its own durable operation records to decide which items are new, which already succeeded, and which genuinely need another attempt.
This separation is especially useful for large offline pipelines. The batch file can be treated as an execution container, while the application database remains the source of truth for job identity. That makes it possible to re-run only missing or failed work rather than replaying an entire dataset.
Streaming does not remove the need for idempotency
Streaming changes the shape of the ambiguity. A user interface may receive hundreds of tokens and then lose the connection before the final event. The application has to decide whether the partial output is useful, whether the user can request another generation, and whether downstream state was already created from the partial response.
The safest pattern is to keep partial model output provisional until the application sees a successful terminal condition. If another component consumes partial output in real time, it should understand that the stream can fail after it has begun. A later retry should create a new attempt under the same logical operation rather than pretending that the token stream can always continue from the exact point of failure.
For interactive text, showing the partial response with an “incomplete” state may be reasonable. For structured extraction, compliance decisions, or tool instructions, partial output should usually not be committed as authoritative data without validation.
Agent loops need idempotent state transitions
Agents complicate the picture because one logical task may contain many model and tool steps. Treating the entire session as one giant atomic operation is usually unrealistic. Instead, state transitions should be idempotent at the level where they can be verified. Read-only tool calls are naturally repeatable. Resource creation needs a deduplication key or lookup step. Updates should ideally use version checks or compare-and-set semantics. Notifications should record delivery IDs.
A robust loop therefore alternates reasoning with state reconciliation. Before a potentially repeated side effect, it asks the system what has already happened. After the side effect, it persists the resulting identifier before moving on. This is closely related to agentic orchestration: the model can choose the next action, but the application owns the transaction boundaries.
When the underlying system does not support idempotent writes, compensating actions may be necessary. That is weaker than preventing duplication, but it is still better than assuming retries are harmless. The workflow should document which actions can be repeated safely and which require human review after an ambiguous failure.
Idempotency keys should also protect security boundaries
Deduplication records can leak information if they are globally predictable or shared across tenants. Keys should be scoped to the correct customer, workspace, or resource boundary, and the deduplication lookup must enforce the same authorization rules as the original operation. A caller should never be able to learn that another tenant used a particular key.
Stored request fingerprints and results also need retention rules. Keeping every prompt forever simply to support deduplication can conflict with data-minimization goals. Often the system can store a hash, operation status, resource identifier, and limited metadata instead of duplicating the full sensitive input. The right choice depends on how long retries remain possible and what evidence operators need.
These concerns align with API security fundamentals: a control is only useful when its scope, lifecycle, and authorization behavior are clear.
Exactly once is usually an application outcome, not a transport feature
Teams often talk about “exactly once” when what they really need is an exactly-once business effect. In distributed systems, that outcome is normally created by combining at-least-once delivery with durable deduplication, state checks, and idempotent side effects. Claude does not change that principle.
The practical design is straightforward: assign stable logical operation IDs, record them before work starts, distinguish model attempts from business actions, make tools idempotent where possible, reconcile state after ambiguous failures, and let retries create new attempts under the same operation. That turns a vague concern about duplicate prompts into a concrete reliability contract.
Once those boundaries exist, retry logic becomes safer. The system can be aggressive about recovering transient model failures without being careless about external effects, and operators can see whether a job succeeded once, failed cleanly, or entered an ambiguous state that requires investigation.
