Help / Developers

Idempotency

Send an Idempotency-Key with every change. A retry gets the first answer and never acts twice.

A network call can fail after it has worked. If you send it again, you must not confirm an order twice or refund twice. An idempotency key makes a retry safe.

The rule #

Send an Idempotency-Key header with every change over REST. In MCP the same thing is the required idempotency_key argument.

Copycurl -X POST "$TEJAS_API/api/2026-11/transactions/$ID/confirm" \
  -H "Authorization: Bearer $TEJAS_API_KEY" \
  -H "Idempotency-Key: confirm-$ID-v3" \
  -H "Content-Type: application/json" \
  -d '{"version": 3}'

Use a new key for each new thing you want done. A good key names what it is for, such as the action, the transaction and its version.

What happens on a retry #

• The first request finished. A retry with the same key and the same body gets the first answer back. The answer carries replayed: true. Nobody is told a second time. The delivery of the answer is none.
• The first request is still running. The retry is 409 with the code idempotency_key_busy. Wait a moment and try again.
• The first request failed. The key is free again. The retry runs.
• The same key with a different body. 422. A key belongs to one request.

Not an Idempotency-Key: the version #

version (or If-Match) guards a different mistake. It stops you from deciding on a transaction that has changed since you read it. Use both on decisions: the key makes a retry safe, and the version keeps you from acting on a stale picture.

Onboarding #

POST /api/2026-11/transactions/buyers does not need a key. The phone number already makes it safe to repeat: the same phone, in any spacing, is the same customer.

Last checked: 2026-11-07