Home
Guides
  1. accounts

Idempotent requests (Accounts API)

Overview

The Accounts API supports optional idempotency on selected POST and PUT requests. Send an Idempotency-Key header. When you retry with the same key and the same request body, you receive the same HTTP status and body as the first completed attempt—including many error responses—so network timeouts and safe retries do not perform the operation twice.

This layer is not the same as a 409 CONFLICT or similar error from banking services on a single attempt. Those responses still describe a business conflict for that call.

When it applies

  • Header: Send Idempotency-Key only when you want this behavior. If you omit it, the request runs normally and nothing is stored for deduplication.
  • Methods: Only POST and PUT are considered. The key is ignored on GET, DELETE, and other methods.
  • Who it applies to: Keys are scoped to the authenticated identity (for example the user or client your session represents). The same key used by two different user's sessions does not collide.
  • Availability: If idempotency is not enabled in a given environment, the header is ignored and behavior is unchanged.

Client usage

Send a unique opaque value (for example a UUID v4) on mutating requests:

POST /accounts/... 
Authorization: Bearer ...
Idempotency-Key: 7f2a8c1e-4b3d-4e1a-9c0f-123456789abc
Content-Type: application/json

{ ... }

Rules:

  • Prefer 128+ bits of randomness (UUID v4 is fine).
  • Max length: 255 characters.
  • Do not embed PII or secrets in the key.

Server behavior

  1. Request validation runs first. If the body or parameters are invalid, that outcome is not tied to the idempotency key (you can fix the request and retry with the same or a new key).
  2. After validation succeeds, if you sent a key and the feature is enabled, the API computes a fingerprint of the operation and your validated JSON body so a different body under the same key can be detected.
  3. First successful path through the API for that key: the result (status code and body) may be stored for replay until expiry.
  4. Retry with the same key and same body: same status and body as the first stored result; the response may include header Idempotent-Replayed: true.
  5. Same key, different body (or different operation treated as a different request): 422 with IdempotencyKeyMismatch.
  6. Same key while a previous attempt is still in progress: 409 with IdempotencyInProgress (retry after the first call finishes).

Retention

Stored replay data is removed automatically after roughly 24 hours. Removal uses time-to-live semantics and can lag slightly beyond the nominal window.

Limitations

  • Coverage: Only transaction mutation endpoints honor Idempotency-Key. On other routes—including remote bank account operations under /user/bank-account/remote (and related paths), and endpoints that return preview or not available responses—the header has no effect and no replay record is kept. Remote bank create is treated as an account setup flow where duplicates are handled by backend rules rather than this header.
  • Response size: Very large response bodies may not be suitable for long-lived replay storage; unusually large payloads may need a different integration pattern.
  • Concurrent requests: Two overlapping calls with the same key can yield 409 until one completes; see server behavior above.

Related