Idempotency

An event ID is not a customer ID

A customer can submit two different inquiries, and both can be valid. Their email address can help locate the customer record, but does not prove the inquiries are the same event. By contrast, two deliveries of the same source message can request the exact same business action again.

Before choosing a key, define what counts as the same action: a particular source event, in a particular system, requesting a particular outcome. If the source provides a stable event ID, store it with its context. When retrying the same action, do not generate a new key just because the previous run did not return a response.

Idempotency describes the intended effect, and does not require an identical HTTP response every time. For example, an action that removes an item can leave it absent even if the response to the repeated request differs from the first response.

Why search then create can produce duplicates

Suppose two processes handle the same event. The first searches for a record and does not find one. Before it can create the record, the second also searches and finds nothing. Both proceed to create it. The search worked in each run, but did not prevent a duplicate across runs.

Enforcing a uniqueness rule requires appropriate protection in the destination. PostgreSQL documents an atomic insert-or-update outcome with ON CONFLICT DO UPDATE, as long as no separate error prevents the operation. This protects a particular database statement, not every business process that uses it, and does not guarantee that the process is idempotent.

Even an atomic update can add another cumulative value or trigger a related action again. Choose a key and a conflict-handling rule that fit the intended action. A marker that someone started handling an event does not prove that handling is complete. A competing attempt should wait according to a defined policy or check the current state.

What to do when the outcome is unknown

A timeout does not mean the other system did not perform the request. First, check the destination using a stable source ID, a saved record ID, or a status lookup supported by the provider. If a completed execution is found, use the existing result instead of creating a new action.

If the provider allows retries, use the same key only while the provider's documented protection remains valid. If the outcome cannot be determined or the key is no longer protected, leave the state as unknown and send it for reconciliation or review by the process owner. A new key is not an automatic solution to uncertainty.

The rules also depend on the API version. Stripe documents that API v1 saves the first response after execution begins, including certain error responses, while API v2 has different retry behavior. So do not assume that every error will be resolved by continuing to send the same request.

Where database protection ends

Creating a record and sending a message are two different effects. If the record is created but the message fails, rerunning the entire process may repeat a step that already succeeded. Store the intent, known state, and result of related actions separately.

An atomic database operation alone does not make an email or external service call part of the same transaction. If the external service does not provide a suitable way to prevent duplicates or determine an outcome, document the limitation and the manual handling path. The checklist table here is a planning and acceptance template, not proof that any provider connection has been activated and tested.

The same order arrives again

As an illustrative example, a process creates a shipping task using the order ID and action purpose as a unique key. If no response is received and the event is delivered again, it checks whether the task already exists and its status before deciding whether to continue. The customer ID alone does not identify the order.

1. Define which event and action the key represents.
2. Store the action key and state in persistent storage.
3. Check whether a task was created at the destination and retrieve its ID.
4. Use the completed result or leave the case for investigation, without blindly creating a new key.

The desired acceptance result is one shipping task for the same action, with evidence in the destination. This is an expectation to verify, not a test result obtained here.

The record was created, but the message status is unknown

In another example, a support inquiry was recorded in the CRM, but an internal update remains in an unknown state. Do not restart the inquiry creation. Check the record and message status separately, and define a recovery path for each related action that fits the service's capabilities.