Idempotency

Basis Theory supports idempotency to guarantee multiple retries of the same request do not unintentionally perform the same operation more than once.

Our API endpoints accept a client-provided Idempotency Key if sent with the BT-IDEMPOTENCY-KEY HTTP header within POST, PUT and PATCH methods.

If an Idempotency Key is not provided by the client, retrying the same request might result in unwanted behavior.

The Idempotency Key must be a unique value generated by the client which is used by the Basis Theory API to identify subsequent requests belong to an original request. The Idempotency Key generation is up to the client, but we strongly recommend using a unique identifier such as UUID to avoid collisions.

When the first request comes in, its response status code and body is saved. Whenever a subsequent request comes in with the same Idempotency Key, the previous stored result will be returned if it succeeded. If the first request failed, the result is not stored and a subsequent request with the same Idempotency Key is processed as a new request. If any subsequent request comes in while the first is still processing, a 409 status code is returned.

If an Idempotency Key is provided for a GET or DELETE request, it is ignored and idempotency logic is not invoked, since these HTTP verbs are idempotent by definition.

All idempotency keys and their respective results are deleted after 24 hours. Therefore, if an Idempotency Key is reused after 24 hours, it will be handled as a new request.

Proxy requests do not currently support idempotency. Please reach out if you would like this capability.

Example

cURL
JavaScript
C#
Python

curl "https://api.basistheory.com" \
-H "BT-API-KEY: <API_KEY>" \
-H "BT-IDEMPOTENCY-KEY: aa5d3379-6385-4ef4-9fdb-ca1341572153"

import {BasisTheory} from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<API_KEY>");

const applications = await bt.tokens.create(
{},
{
  idempotencyKey: "aa5d3379-6385-4ef4-9fdb-ca1341572153",
}
);

using BasisTheory.net.Api;
using BasisTheory.net.Client;
using BasisTheory.net.Model;

var apiInstance = new TokensApi(config);
var response = await apiInstance.CreateAsync(new CreateTokenRequest {...}, 
    requestOptions: new RequestOptions
    {
        IdempotencyKey = "aa5d3379-6385-4ef4-9fdb-ca1341572153"
    });

import basistheory
from basistheory.api import tokens_api

api_client = basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<API_KEY>"))
client = tokens_api.TokensApi(api_client)

client.create(request_options=basistheory.RequestOptions(idempotency_key="aa5d3379-6385-4ef4-9fdb-ca1341572153"))

Example​

Example