Idempotent requests

Our Premium Bank API supports idempotency to safely retry requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a transfer does not go through due to a network connection error, you can retry the request with the same idempotency key to guarantee that only the single transfer originally attempted is created.

To perform an idempotent request, provide an additional Idempotency-Key request header. We recommend using a V4 UUID. If the API call fails with a network error or responds with a 5XX, 409, or 429 status code, we expect the caller to perform retries with the same Idempotency-Key header until it responds differently. For any other response code, especially other 4XX errors, there is no point in attempting retries, as we will always return the same result.

When a previous response is replayed, the response includes an additional HTTP header: Idempotent-Replayed: true.

Idempotency keys will persist in the API for 24 hours. If an original request is still being processed when an idempotency key is reused, the API will return a 409 Conflict error (which is safe to retry).

Subsequent requests must be identical to the original request, or the API will return a 422 Unprocessable Entity error. We do not support setting an idempotency key on GET and DELETE requests, as these requests are inherently idempotent.