Idempotent requests

Our Premium Bank API supports idempotency for safely retrying 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. In case 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 send the same result.

When a previous response is replayed, the response is sent with 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.