Skip to content
CheckcraftDownload
Practical workflow

HTTP idempotency: how to check that a repeated request does not create a second order

Checkcraft is a desktop app for checking APIs and logs without code, with a free edition. Download, no sign-up →

A payment sandbox sends a notification twice, a customer presses "Pay" again, the network drops and the request is retried. If the API is not idempotent, you get a second payment or a second order. Here is what idempotency means and how to check it.

Checkcraft ·

Get help with your first test →

What idempotency is

A request is idempotent if repeating it several times has the same effect as doing it once: the server state does not change further. Under RFC 9110, PUT, DELETE and the safe methods GET, HEAD, OPTIONS and TRACE are idempotent. POST and PATCH are not by definition, so APIs that create payments and orders add an idempotency key.

The idempotency key

The client sends a value unique to the operation in a header. In YooKassa, for example, it is the Idempotence-Key header, unique for the operation on the shop side. On a request with a known key the server returns the result of the first operation instead of running it again.

How to check

Send the same request twice with the same key and compare the responses: the payment ID must match. Then check the side effects, not only the response: one record in the database, one "created" event in the logs by traceId. A new key must produce a new operation. Separately check a request without a key and a repeat with the same key but a different body: what your API should do there is up to the requirements.

# 1. The same request twice with the same key
POST /payments   Idempotence-Key: 7f3a…   → 200, payment_id = P1
POST /payments   Idempotence-Key: 7f3a…   → 200, payment_id = P1  (the same!)

# 2. Check the side effects, not only the response
SELECT count(*) FROM payments WHERE order_id = 5001;   -- expect 1
logs by traceId: one "payment created" record, not two

# 3. A new key means a new operation
POST /payments   Idempotence-Key: 9b1c…   → a new payment_id

Why one response is not enough

Both responses can return 200 with identical fields while the database ends up with two rows. So a repeated request is checked against three sources: the response, the log by traceId and the database record. In Checkcraft that is one check: the request, a Kibana search by traceId and a SELECT in the database (database checks are in Pro).

Next step

Repeat this on your own API

Checkcraft is a desktop app that saves API response checks without code and shows what did not match. Start with a sample, then use your own sanitized data. Free runs on Windows and Linux with no time limit.

Download FreeDownload and first run

No sign-up or email needed, the archive is ready in a couple of minutes. See the edition limits.

References

RFC 9110: idempotent methods · YooKassa: interaction format and Idempotence-Key

Start with the linked example and compare its result with your own test requirement.

Ask a person

Get help with your first test

Tell us what you want to test or where you got stuck. We can help you start Checkcraft, choose an example and understand your first run. You can ask before downloading.

The Telegram group is public: do not post passwords, tokens or confidential work data. A description of your task is enough to start.

You can also email us support@checkcraft.ru

No account required. We will reply by email. This is a support request, not a newsletter subscription.