Idempotency

When an operation can potentially mutate resources within a system, you may supply an idempotency key. The key is used to assure that, no matter how many times the operation is applied, the mutation only takes place at most once.

The key is required on every mutating partner request. A POST, PUT, PATCH or DELETE sent without an X-Idempotency-Key is rejected:

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

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

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. 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.