Idempotency

Optional security from accidental rewrites

Our API optionally supports idempotency, which allows you to safely retry requests without accidentally performing the same operation twice. When you create or update an object, you can provide an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.

To perform an idempotent request, provide an additional Idempotency-Key header:

Idempotency-Key: <key>

Our idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Any subsequent requests with the same key will return the same result.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you. Idempotency keys can be up to 255 characters long. There are two common strategies for generating idempotency keys:

  • Use an algorithm that generates a token with enough randomness, like UUID v4
  • Derive the key from a user-attached object, like your internal ID for a given cardholder: this provides a relatively straightforward way to protect against double submissions

Keys automatically expire after 24 hours and a new request is generated if a key is reused after the original has been deprecated.

Our APIs will return ‘409’ errors if there is an issue with idempotency, giving more detail in the ‘msg’ field of the response. These errors are returned if:

  • A subsequent request with an idempotency key has a different request path to that of the original request
  • A subsequent request with an idempotency key has a different request body to that of the original request
  • Subsequent requests are sent whilst an original matching request with the same idempotency key is still in-flight

When deciding when to retry requests, our APIs respond with a GiveCard-Should-Retry header on responses to advise a client when to retry.

GiveCard-Should-Retry: <bool>
  • GiveCard-Should-Retry set to true indicates that a client should retry the request. Clients should still wait some amount of time (probably determined according to an exponential backoff schedule) before making the next request so as not to overload the API.
  • GiveCard-Should-Retry set to false indicates that a client should not retry the request because it won't have an additional effect.