Skip to main content
When a request’s response is lost, for example to a timeout or a dropped connection, you can’t tell whether the write happened. Retrying without protection can provision and bill a second network token, create a second PCI token that takes a second slot of your token limit, or request a second cryptogram for the same payment; not retrying can lose the first one. Send an X-Idempotency-Key header with the write, and repeat the request with the same key until you get a response. Guardian executes the write at most once per key and answers every repeat with the original outcome.
In this release, idempotency keys cover these writes:On any other endpoint, the header has no effect on Guardian. A forward sends it on to the destination, see Forwards. A request without the header behaves exactly as before, with one exception: a repeated Google Pay payload, see Wallet tokenization.Idempotency is switched on per Guardian instance. On an instance where it isn’t switched on, the header is ignored and every request is executed. Ask Hellgate support whether it’s on for yours.

At a glance

Send a key

  • Format. A key is 1 to 255 characters, each a visible ASCII character (! to ~), sent as a single header value. A random UUID works well. Never put card data in a key.
  • One key per write. Use a new key for every write you mean to make, and reuse it only to repeat that same request.
  • Same request. A repeat must send the same JSON body and the same path and query parameters. The order of keys in the body doesn’t matter. Headers such as x-request-id don’t count, so you may send a new request ID with each repeat. The card’s security code doesn’t count either: see Card security code.
  • Scope. A key belongs to the credential that sent it and to the operation. A credential is an API key, the subject (sub) of an access token, or the instance’s legacy API key. Access tokens with the same subject share their keys, so a repeat with a renewed token still finds the original. The same key sent by another credential, or to another operation, is unrelated: it neither collides with nor reveals the other outcome.

Card security code

The card’s security code, source.security_code, is the only body field left out of the comparison. Guardian keeps nothing derived from it. A repeat that differs from the original only in the security code is the same request: it replays the original outcome and doesn’t use the new security code. For a PCI token created from pan, the replay returns the original token. Its security code is the one from the original request, and Guardian holds it only for 15 minutes from the original create; a replay doesn’t renew it. To correct card data, including the security code, send the request with a new key. A security_code key anywhere else, such as in metadata or in a generic token’s payload, counts like any other field: a repeat that changes it is refused with 422 IDEMPOTENCY_KEY_MISMATCH.

Repeats

A repeat returns the original’s status code and response, with the response header Idempotent-Replayed: true. Nothing is executed again: no token is created or provisioned, no cryptogram is requested, no slot of your token limit is used, and nothing is billed. Other responses don’t carry the header. A success and a refusal of the request itself, such as a validation error, a card that isn’t eligible or a card scheme without network token support, are stored and replayed. For a PCI token, that includes a refusal because your instance’s PCI token limit is reached, because your compliance level doesn’t allow a pan source, or because a test card was sent in the Production tier. What a replay returns for each write is under Replay content.
A refusal because the PCI token limit is reached replays for 24 hours, even after you delete tokens. Once you have freed slots, send the request with a new key.
Two wallet refusals depend on your instance’s configuration, and they also replay for 24 hours, even after the configuration is fixed: 422 APPLE_PAY_UNKNOWN_CERTIFICATE for an Apple Pay payload encrypted for a certificate that isn’t registered yet, and 422 GOOGLE_PAY_DECRYPTION_FAILED for a Google Pay payload encrypted for a key that isn’t active yet or has been retired. Once the configuration is fixed, send the request with a new key.

Replayed refusals

A replayed refusal keeps the original’s status code, classifier and body structure. Every message in the body, at any depth, is replaced by a fixed text, so no message from a token service is kept:

Refusals

Guardian refuses these requests without executing them. None of these refusals is stored, so a later repeat is checked again. An original that hasn’t finished 5 minutes after it started no longer counts as running: a repeat then executes again, as after an unknown outcome.

Outcomes that aren’t stored

These outcomes aren’t stored, so a repeat executes the request again:
  • an unknown outcome, or any response with a status of 500 or above;
  • the idempotency refusals above;
  • authentication and authorization failures;
  • a refusal because a feature is off for your instance: network token support, agentic commerce support, or delegated authentication support for a dauth cryptogram. Once the feature is on, a repeat runs;
  • a token service refusal that concerns Guardian’s own access to the service rather than your request: an authentication, permission or configuration problem, a request timeout or a rate limit.

Unknown outcomes

Only a network token provisioning and a cryptogram request can have an unknown outcome. PCI and generic token creation and wallet tokenization write only to Guardian’s own storage, and a keyed create stores its token together with its outcome: if it fails, it leaves no token, and a repeat executes again. A keyed PCI token create whose security code can’t be stored answers 503 with the classifier CUSTODY_UNAVAILABLE, leaves no token, and can be repeated with the same key. So does a keyed network token provisioning from a pan source whose security code can’t be stored: Guardian calls no token service and stores nothing, and a repeat with the same key executes again. The outcome of a provisioning is unknown when Guardian called the token service and the service:
  • gave no answer, because of a timeout or a dropped connection;
  • gave an answer Guardian couldn’t read;
  • answered with a server error;
  • or provisioned a token that Guardian then failed to store.
This holds whatever status Guardian answers you with, which can be a 4xx. So don’t decide from the status whether to retry: repeat with the same key, and Guardian either replays a stored outcome or executes again. After an unknown outcome, Guardian has stored no network token and billed nothing, so a repeat executes the request again. Per key, Guardian keeps at most one network token and bills at most one.
On the lost attempt, the token service may have provisioned a token that Guardian never stored. Guardian doesn’t know that token and never returns it. A repeat provisions a new one.
The outcome of a cryptogram request is unknown when the token service gave no answer, gave an answer Guardian couldn’t read, or answered with a server error, or when Guardian failed to store or return the cryptogram it got. Guardian then stores nothing for the key, and a repeat requests a fresh cryptogram. The token service may have issued a cryptogram on the lost attempt that Guardian never returns.

Retention window

Guardian keeps a stored outcome for 24 hours from the original request. After that, a request with the same key executes as a new request. The window isn’t configurable. The window can end early: Guardian derives its idempotency records from an instance secret, which Hellgate operators rotate only rarely. After a rotation, a repeat of an earlier request executes as a new request.

Replay content

A replay is rendered from the current state of what the original created, not from a copy of the original response. The one exception is an inline cryptogram, see Cryptogram requests. A replay shows the token as it is now, with the original status code. After a stored refusal, a replay returns the refusal, as under Replayed refusals. When the token has been deleted since, or has expired, the replay answers 410 with the classifier IDEMPOTENCY_KEY_TOKEN_DELETED and the header Idempotent-Replayed: true, and returns no token data. Nothing is created or provisioned again.

Network token provisioning

A network token whose status changed since, for example one the scheme made inactive, is returned with its current status. Card fields follow the paired PCI token, as Get network token shows them.

PCI token creation

Generic token creation

A replay returns the generic token as Get generic token renders it now, without its payload, as the create response does.

Cryptogram requests

Guardian holds an inline cryptogram requested with a key for as long as a cryptogram_reference lives: 15 minutes from the original request by default. After that, a replay still answers 200, so check for null in number before you use the response. To get a cryptogram, request a new one with a new key. When Guardian holds the cryptogram but can’t read it at the moment, the replay answers 503 with the classifier CUSTODY_UNAVAILABLE and changes nothing. Repeat it later with the same key. When the network token has been deleted since, the replay answers 410 IDEMPOTENCY_KEY_TOKEN_DELETED, in either mode.

Wallet tokenization

A replay never returns a cryptogram, and Guardian reads or writes no cryptogram for it. When the wallet token has been deleted since, the replay answers 410 IDEMPOTENCY_KEY_TOKEN_DELETED. Both wallets also recognize a payload tokenized before when it’s sent again without a key. On an instance where idempotency is switched on, they answer: These answers don’t carry Idempotent-Replayed, and no second wallet token is created. A payload is matched across your whole instance, not per credential, so a payload that another credential tokenized returns that credential’s wallet token. A keyed request for a payload tokenized before gets the same 200, and its repeats replay it. On an instance where idempotency isn’t switched on, Apple Pay answers the same way, and Google Pay refuses every repeated payload with 409 GOOGLE_PAY_DUPLICATE_PAYLOAD.

Forwards

Guardian doesn’t deduplicate forwards: Forward card data, Forward cryptogram and Forward wallet token. A repeated forward is sent to the destination again, so whether a repeat is safe is up to the destination. If the destination accepts an idempotency key, send it as X-Idempotency-Key. Guardian passes the header on to the destination, whether or not idempotency is switched on for your instance.
  • Unchanged. A key of visible ASCII characters (! to ~) arrives at the destination as you sent it. Guardian doesn’t check, store or compare it, so the destination’s rules for the key apply, not the format under Send a key. Never put card data in a key.
  • Single-use credentials. A repeat can’t reuse a credential the first forward consumed. A network token forward with a consumed cryptogram_reference is refused with 400 REFERENCE_ALREADY_CONSUMED, and a wallet token with a cryptogram (Apple Pay, or Google Pay CRYPTOGRAM_3DS) whose cryptogram is consumed with 400 CRYPTOGRAM_CONSUMED, as without a key. Nothing is sent. To repeat a network token forward, request a new cryptogram and send the new reference with the same key.
  • Response headers. Any idempotency header in a forward’s response, such as Idempotent-Replayed, comes from the destination, not from Guardian.