Duplicate Orders When Working with the API: Causes and Protection

Why duplicates appear after a single action

A panel owner may click a button once and see several identical orders: for followers, views, reactions, or another service. Usually the problem isn't the click itself, but the chain between the client, the API, the database, and the provider.

From the server's point of view, "one request" isn't always one. The client may not have received a response and resent the request, while the first operation had already been saved. Sometimes an order is created once in the panel's database but is sent to the provider twice. These are different scenarios, and they are fixed in different ways.

A timeout doesn't mean the order wasn't created

The most common cause is that the client waits for a response for a limited time. The server accepts the request, creates the order, but responds later than the set timeout. The client considers the operation unsuccessful and sends it again.

As a result, the first order is already in the database, and the second request creates another one. This happens especially often with a slow response from an external API, an overloaded queue, or an unstable connection between services.

A timeout only indicates the absence of a response, not the absence of request processing.

Automatic retries on the client side

HTTP request libraries, background jobs, and integration services often retry requests automatically. The trigger may be a connection error, a server response code, a network interruption, or a response that takes too long.

A retry is useful in itself: it reduces the number of lost orders during temporary failures. The downside of this approach is that, without protection against reprocessing, it turns any network instability into duplicates.

• a retry may be triggered in the website or bot code;
• a queue may restart the job;
• a proxy or integration module may repeat the request;
• an operator may manually resend the order after an error.

A repeated request arrives before the first response

Sometimes two identical requests really do reach the API almost simultaneously. For example, the user submitted the form twice, the frontend didn't block the button, or a background job started again before the first one finished.

If the handler first checks whether the order exists and then creates it, two parallel operations can pass the check at the same time. Each will see that the order doesn't exist yet, and each will add a new record.

This situation is called a race condition. A simple preliminary check in the code doesn't fully protect against it. The downside of a check without a constraint at the database level is that it breaks under parallel load.

The order was recorded, but the API response was lost

A request goes through several stages: the server receives the data, creates the record, puts the job in the queue, and sends the response. A failure can occur between any of them. For example, the database has already confirmed the creation of the order, but the connection dropped before the response was delivered to the client.

The client doesn't know whether the order was accepted and repeats the operation. An API without a separate verification mechanism treats the request as new. In the log, this often looks as if the service created two orders "by itself," even though it had two incoming calls.

An idempotency key for creating an order

Creation operations need a unique idempotency key. The client generates it before the first send and passes it along with the order parameters. On a retry due to a timeout or error, the same key is used.

The API stores the key together with the processing result. If a request arrives with an already known key, the server doesn't create a new order but returns the result of the first call: the order ID, its status, or a previously generated error.

One key must correspond to one business operation, not to one HTTP connection.

The downside of the method is that keys need to be stored, cleaned up according to rules, and verified on the API side. If a new key is generated on every retry, the protection won't work. If one key is used for different orders, some new operations will be mistakenly rejected.

Uniqueness must be enforced by the database

Idempotency is best complemented by a uniqueness constraint in the database. For this, a combination is chosen that uniquely describes the order: the internal client ID, the idempotency key, the service type, and other required fields.

The database must reject the second record even if two handlers reached the creation step simultaneously. After a conflict, the API returns the existing order rather than an error without explanation.

The downside of a strict unique constraint is that it can't be built on the link or username alone. A client may deliberately order the same service for the same channel several times. Too broad a constraint will block legitimate repeat purchases.

A queue may deliver a job more than once

Job queues often operate on an "at least once" delivery principle. If a worker processed a job but didn't manage to acknowledge its completion, the queue may hand the same job to another worker again.

For the queue, this is a normal way not to lose a job. For creating an order without idempotency, it's a source of duplicates. The job ID or a separate operation key must be passed all the way to the final handler, including the module that sends the order to the provider.

The downside of disabling redelivery is that some orders may be lost if a worker crashes. It's safer to accept possible retries and make the handler resilient to them.

Duplicates arise between the panel and the provider

An internal order may be created once, but the request to the external API is sent twice. The reason is the same: the panel didn't receive a response from the provider and decided to resend. If the provider had already accepted the first request, two identical orders will appear on its side.

A separate link between the internal order and the external one is needed: a send ID, an idempotency key, or a stored provider response. You can't assume that protection at the entrance to your own panel will automatically protect outgoing calls.

The downside of reconciliation with a third-party API is that not every provider supports lookup by an external key. In that case, you have to record send attempts and separately investigate indeterminate statuses.

A webhook must not create a new order

Webhooks report changes: an order was accepted, started, completed, canceled, or requires review. The error occurs when the webhook handler treats the notification as a command to create the order again.

The same webhook may arrive repeatedly. The sender retries delivery if it didn't receive an acknowledgment, and notifications sometimes arrive out of order. The handler must find the existing order by the external ID and update the status.

The downside of processing webhooks only by receipt time is that a late notification may overwrite the current status with an outdated one. Event IDs, status versions, or clear transition rules are needed.

Which records will help find the source of duplicates

To investigate, it's not enough to see only two order numbers. You need data on each processing stage: request time, idempotency key, client ID, order parameters, background job number, external API response, and resend attempts.

• match duplicates by the operation key, not just by the link;
• check whether identical requests were in the incoming API log;
• see whether the job was repeated in the queue;
• separate the creation of the internal order from sending it to the provider;
• save the external order ID immediately after receiving the response.

The downside of logs that are too short is that the source of the problem disappears before it can be analyzed. The downside of excessive logging is that tokens, personal data, and other sensitive fields may end up in the records, so they need to be masked.

How to handle an indeterminate request result

After a timeout, you can't immediately create the order again with new data. First, the API must check the operation by the idempotency key or client ID. If the order is found, its current state is returned. If processing is still ongoing, the client receives a waiting status.

1. Create the operation key before the first request.
2. Send the same key on every retry.
3. Save the key and the order in a single protected database operation.
4. Pass the operation ID to the queue and the external API.
5. Return the previously created order on a repeated call.

Such a scenario requires changes to the API and the client integration. Its downside is more complex debugging and more order states, but a repeated request delivery no longer automatically means a repeat purchase.