Idempotency and safe retries

Why you need it

Networks fail after the server has acted but before you get the response. Without protection, your retry re-submits the application, provisions a second payment link, or runs a duplicate identity check. An idempotency key closes that gap: the first request that carries a given key executes; every later request with the same key returns the stored result of the first, byte for byte, without re-executing.

Using a key

curl -s -X POST https://hub.credicorp.co.uk/partner/v1/applications \
  -H 'Authorization: Bearer '$TOKEN \
  -H 'Idempotency-Key: 3b1e-app-2026-07-04-0001' \
  -H 'Content-Type: application/json' \
  -d @application.json

Generate a unique key per logical operation — a UUID, or a deterministic key derived from your own record ID so a retry of the same operation reuses it. Reusing a key for a different payload is an error, not a shortcut.

Scope and lifetime

A key is scoped to the endpoint and your project, and is retained for a bounded window (long enough to cover realistic retries, not forever). Store the key with your own record so a later worker retrying the same job presents the same key. Idempotency pairs naturally with retry-with-back-off and with webhooks, whose delivery you should also treat idempotently on your side.

Frequently asked questions

Do reads need an idempotency key?

No. GET requests are already idempotent — repeating them has no side effect. Idempotency keys are for mutating calls (POST/PUT/PATCH) where a replay could otherwise act twice.

What if I reuse a key with a different body?

That is rejected. A key is bound to the first payload it saw; presenting the same key with a different body returns an error rather than silently acting. Use a fresh key for a genuinely new operation.