Create endpoints accept an idempotency key

A client can safely repeat a POST that creates something, because the server recognizes the repeat.

HighChecked by hand

Applies to:
Services with POST endpoints
Rule id:
api.idempotency-keys-on-create

Why it matters

When a POST times out, the client can't tell whether the request never arrived or the response was lost. If it retries and the first attempt had succeeded, there are now two orders or two payments. Without a way to recognize the repeat, the client has to choose between duplicates and giving up.

How to apply it

  • Accept an Idempotency-Key header (a client-generated unique value) on every endpoint that creates a resource or triggers a side effect.
  • Store the key with the result, in the same transaction as the write. On a repeat, return the stored result and do nothing else.
  • Reject a key that is reused with a different request body.
  • Keep keys at least as long as clients may retry: a day is a common floor.

Example

POST /v1/payments with Idempotency-Key: 7f3c… is sent twice after a timeout. The second call returns the first call's 201 and payment id; the card is charged once.

References

Checklists with this rule

Related agent skill: idempotency-deduplication

  • API paths carry a version

    Every REST path includes a version segment, so a breaking change can ship next to the old contract.

    MediumChecked automatically

  • Every endpoint is described

    Each REST endpoint says what it does, so callers and coding agents do not have to guess from the path.

    MediumChecked automatically

  • The API is covered by contract tests

    Tests check that the service still answers the way its consumers expect, and run before every release.

    MediumChecked by hand