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.Tokens;
var client = new TokenClient("<API_KEY>");
await client.GetAsync(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"))