Skip to main content

Idempotency

Most methods on resources in the finperks Giftcard API can or even must be used in an idempotent way, so you can automatically retry requests without having unintended side effects.

Retrying requests makes your system more resilient when network failures happen, our system temporarily fails to process your request or you exceeded the rate limit. We highly recommend implementing automated retries - they are necessary for reliable use of any network-based API.

The Idempotency-Key Header​

The endpoints POST /orders and POST /retail_orders require an Idempotency-Key header:

Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
  • The key may be up to 40 characters long and consist of letters, digits, _ and - (^[a-zA-Z0-9_\-]+$).
  • Use a fresh, unique value for every order you intend to create — a random UUID (version 4) is a good choice. Generate it once per order attempt and persist it together with the order in your system before sending the request, so it survives a crash of your own process.
  • The idempotency key is part of the request signature, so the retried request must be signed accordingly.

Retry Semantics​

When you send a request with an Idempotency-Key that was already used:

  • Same key, identical request body: the previously created order is returned, including its id and current state. No second order is created and no value is delivered twice. This is what makes retries safe.
  • Same key, different request body: the request is rejected with HTTP status 400 and the error code reused_idempotency_key. The key identifies one specific order creation — never reuse it for a different order.

Idempotency keys are kept for a suitable amount of time to cover automated retries. Retries are intended for the seconds and minutes after the original attempt; do not rely on replays long after the original request.

Recovering From Network Failures​

If you sent an order creation request but never received a response (timeout, connection reset, crash), you cannot know whether the order was created. Do not create a new order with a new key — that could result in a duplicate. Instead:

  1. Retry the identical request with the same Idempotency-Key. If the order was created, you receive it back including its id and current state. If it was never created, it is created now.
  2. Check the state of the returned order. A sync order may have completed even though your original request timed out — or it may still be processing, in which case the retry returns the order in the processing state even in sync mode. Keep polling GET /orders/{id} or wait for the webhook event until the order reaches a final state.
  3. Proceed as usual: deliver the gift card, or — if the surrounding transaction on your side failed — invalidate the order via POST /orders/{id}/actions/invalidate as soon as possible. See Order Lifecycle.

When retrying after a 429 rate limit response, wait at least the duration indicated by the Retry-After header, see Rate Limiting.