Idempotency

An idempotency key assures that, no matter how many times an operation is applied, the mutation takes place at most once.

The key is mandatory on mutating partner requests — see which endpoints require a key for the exact list. A POST, PUT, PATCH or DELETE to one of them sent without an X-Idempotency-Key is rejected:

{
  "error": "Bad Request",
  "message": "X-Idempotency-Key header is required for this request"
}

This is enforced in Sandbox (UAT) and Production alike — the sandbox is not the more permissive of the two, so a request that passes there passes at cutover.

Each key is scoped per credential, so your keys can never collide with another partner’s.

Which endpoints require a key

Every mutating endpoint on the live partner surface requires one:

Endpoint	Key required
POST /v1/customers	Yes
PATCH /v1/customers/{id}	Yes
POST /v1/ussd/session	Yes
POST /v1/ussd/process	Yes
POST /v1/oauth/revoke	No

Note

POST /v1/oauth/revoke is the one exception. It is a POST, but it carries no body and revoking an already-revoked token is inherently idempotent, so it does not take a key. Sending one is harmless — it is ignored — but because it is optional there, do not cover x-idempotency-key in that request’s signature base unless you are actually sending the header. Covering a component the request does not carry is itself a 401.

Representation in a Request

Idempotency keys are universally unique identifiers and should be passed into the header as X-Idempotency-Key.

  curl --request POST \
    --url https://api.staging.pipevest.com/v1/customers \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <access-token>' \
    --header 'x-client-id: <client-id>' \
    --header 'X-Idempotency-Key: b9fa7097-befa-4869-a91b-a7f79400d917' \
    --data '{"firstName": "John", "lastName": "Doe"}'

When to use them

Supply an idempotency key on every mutating request, with the one exception noted above. Read-only requests never need one, and it is ignored if you send it.

Request Type	Idempotency key
GET	Not used
POST	Required
PUT	Required
PATCH	Required
DELETE	Required

How retries behave

Because the key is scoped per credential, the API can safely deduplicate retries:

• Completed request replayed — a retry with the same key after the original operation finished replays the stored response verbatim (identical status code and body). The handler does not run again, so the mutation happens at most once.
• Concurrent retry (409 Conflict) — if you retry while the first request with that key is still in flight, the API returns 409 rather than running the operation twice.
• Same key, different payload (422 Unprocessable Entity) — reusing a key with a different request body is a client error and is rejected, so a key can never mask two different operations.