Retry a financial request safely

Bind one idempotency key to one financial request intent and its durable operation.

Every financial mutation that declares Idempotency-Key in OpenAPI permanently binds one random key to one validated request intent. Reuse that key only when retrying the identical intent.

Generate a 256-bit key

The key must contain exactly 32 random bytes encoded as 43 unpadded base64url characters. Generate it with a cryptographically secure random source.

This TypeScript example creates a valid key with Node.js:

import { randomBytes } from 'node:crypto';

const idempotencyKey = randomBytes(32).toString('base64url');

Create the key before the first request. Store it with your local request record until you receive and persist the operation identifier.

Never derive the key from account data, time, or request fields. Do not log it or place it in a URL.

Bind the key to one request intent

Send the key only when the OpenAPI operation declares the Idempotency-Key header as required. Perflo binds it to these values:

• The current resource owner and client
• The stable OpenAPI operation ID
• Validated path and query values
• Validated semantic headers
• The validated request body; an absent body equals explicit JSON null

Authorization, DPoP, request ID, and the idempotency key itself do not change the request intent. JavaScript Object Notation (JSON) member order and equivalent normalized values also do not create a different intent.

Retry the identical request after a lost response

If you lose the response, send the same validated request with the same idempotency key. An equal replay returns the existing operation and includes:

Idempotent-Replayed: true

The binding does not expire. The same replay returns the existing operation after any elapsed time.

If the key already belongs to a different intent, Perflo returns 409 with code idempotency_key_conflict. It never assigns that key to a new operation.

Use a new key for a new intent

Generate a new key whenever any validated semantic value changes. This includes changing an amount, destination, path parameter, or other operation input.

Different clients can use the same random key without sharing an operation. Perflo isolates key authority by resource owner, client, and route.

Do not generate a new key for an uncertain submission. Read the existing operation as described in Track a financial operation.