Idempotency

Idempotency on the Tekmerion API is bounded and per-endpoint, not a blanket guarantee. An endpoint provides replay protection only where its contract explicitly defines it. Where it does not, retries are not automatically deduplicated. This page states exactly what is and is not guaranteed.

Two distinct mechanisms

There are two separate things named "idempotency" at this API, and they MUST NOT be conflated.

1. The idempotency_key request field

Some command endpoints accept an idempotency_key in the request body. This is the caller-visible idempotency contract. Where an endpoint documents it (for example, payment-intent creation):

• idempotency_key is a caller-supplied opaque string.
• It is scoped to the merchant. Two different merchants using the same key string do not collide; their key spaces are separate.
• A repeat call with the same key and semantically equivalent input returns the same resource — no new record is created and the original side effects are not re-triggered.
• A repeat call with the same key but different input is rejected with IDEMPOTENCY_CONFLICT. The key is consumed; generate a fresh key for a genuinely different request.
• Deduplication is bounded by a 24-hour deduplication window. Within the window the rules above hold; outside it, the same key may create a new resource. The idempotency_key is an opaque string with no enforced maximum length — use a compact token such as a UUID or your order identifier. See Reference.

Supply an idempotency_key on every command where it is offered — derived from your own order identifier or a fresh per-attempt UUID — so that a network retry cannot create a duplicate resource.

2. The Idempotency-Key request header

An endpoint MAY accept an Idempotency-Key request header as a transport carrier. This header does not manufacture guarantees:

• It MUST NOT create stronger semantics than the endpoint's own contract already defines.
• On an endpoint that defines caller-visible idempotency, the header MAY carry that key.
• On an endpoint that defines no idempotency contract, sending the header does not make the call idempotent. The retry is processed as a new call.

Never rely on the header alone to prevent duplicates. Rely on the endpoint's documented idempotency_key field.

What is not guaranteed

• Without a key, command retries are not deduplicated. Each call to a creation endpoint without an idempotency_key produces a distinct resource. Re-submitting is not a no-op.
• Idempotency is not global. A key is meaningful only on the endpoint and merchant scope where it was used. The same string carries no relationship across different endpoints.
• The window is finite. Replay protection does not extend indefinitely; past the deduplication window a reused key is treated as new.

Reads

Read endpoints (singleton and collection) are naturally repeatable — calling them again returns the current state and changes nothing. An idempotency key is irrelevant to a read and is ignored.