> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Retry a write safely with the X-Idempotency-Key header: a repeat returns the original outcome instead of executing again.

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.

> [!NOTE]
>
> In this release, idempotency keys cover these writes:
>
> * [Create network token](https://developer.hellgate.io/products/guardian/api-reference/network/create-token.md) (`POST /api/network/tokens`), for every source: `pan`, `pci_token`, `wallet_token` (promotion) and `session`.
> * [Create PCI token](https://developer.hellgate.io/products/guardian/api-reference/pci/create-token.md) (`POST /api/pci/tokens`), for both sources: `pan` and `session`.
> * [Create generic token](https://developer.hellgate.io/products/guardian/api-reference/generic/create-token.md) (`POST /api/generic/tokens`).
> * [Request cryptogram](https://developer.hellgate.io/products/guardian/api-reference/network/request-cryptogram.md) (`POST /api/network/tokens/:id/cryptograms`), in both modes: `inline` and `reference`.
> * [Tokenize Apple Pay](https://developer.hellgate.io/products/guardian/api-reference/wallet/tokenize-apple-pay.md) (`POST /api/wallet/apple-pay/tokenize`).
> * [Tokenize Google Pay](https://developer.hellgate.io/products/guardian/api-reference/wallet/tokenize-google-pay.md) (`POST /api/wallet/google-pay/tokenize`).
>
> On any other endpoint, the header has no effect on Guardian. A forward sends it on to the destination, see [Forwards](#forwards). A request without the header behaves exactly as before, with one exception: a repeated Google Pay payload, see [Wallet tokenization](#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

| You send | Guardian answers |
| - | - |
| A new key | Executes the request as usual. |
| A repeat of a request whose outcome is stored | The original status and response, with the header `Idempotent-Replayed: true`. Nothing is executed. |
| A repeat while the original is still running | `409` `IDEMPOTENCY_KEY_IN_USE`, at once. |
| The same key with a different request | `422` `IDEMPOTENCY_KEY_MISMATCH`. |
| A repeat after an [unknown outcome](#unknown-outcomes) or an [outcome that isn't stored](#outcomes-that-arent-stored) | Executes the request again. |
| A repeat more than 24 hours after the original | Executes the request as a new one. |

## Send a key

```bash theme={null}
curl --request POST \
  --url 'https://<your-instance>/api/network/tokens' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --header 'X-Idempotency-Key: 5f0c6a8e-3b1d-4c47-9a7e-2d8f1b6c4e90' \
  --data '{"source": {"type": "pci_token", "pci_token_id": "<PCI-TOKEN-ID>"}}'
```

* **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](#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](#replay-content).

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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:

```json theme={null}
{
  "code": 400,
  "classifier": "NETWORK_TOKEN_NOT_SUPPORTED",
  "message": "The original request was refused. This is a replay of that refusal."
}
```

## Refusals

Guardian refuses these requests without executing them. None of these refusals is stored, so a later repeat is checked again.

| Status | Classifier | Cause |
| - | - | - |
| `400` | `IDEMPOTENCY_KEY_INVALID` | The key is empty, longer than 255 characters or contains a character outside `!` to `~`, or the header was sent more than once. |
| `409` | `IDEMPOTENCY_KEY_IN_USE` | The original request with this key is still running. Repeat it later. |
| `422` | `IDEMPOTENCY_KEY_MISMATCH` | The key was already used by the same credential for the same operation with a different request, whatever the original's outcome. |
| `410` | `IDEMPOTENCY_KEY_TOKEN_DELETED` | The request repeats one whose token has been deleted since, or has expired. See [Replay content](#replay-content). |

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](#unknown-outcomes).

## Outcomes that aren't stored

These outcomes aren't stored, so a repeat executes the request again:

* an [unknown outcome](#unknown-outcomes), 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](https://developer.hellgate.io/products/guardian/tokens/network-tokens.md#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.

> [!WARNING]
>
> 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](#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](#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

| Source | A replay returns |
| - | - |
| `pan`, `pci_token` | The network token, as [Create network token](https://developer.hellgate.io/products/guardian/api-reference/network/create-token.md) renders it. |
| `wallet_token` | The source wallet token ID and the promoted network token. |
| `session` | The session ID. |

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](https://developer.hellgate.io/products/guardian/api-reference/network/get-token-details.md) shows them.

### PCI token creation

| Source | A replay returns |
| - | - |
| `pan` | The PCI token as [Get PCI token](https://developer.hellgate.io/products/guardian/api-reference/pci/get-token-details.md) renders it now, with the card masked. A replay never returns the security code. |
| `session` | The original session ID. No second session is opened. |

### Generic token creation

A replay returns the generic token as [Get generic token](https://developer.hellgate.io/products/guardian/api-reference/generic/get-token-details.md) renders it now, without its payload, as the create response does.

### Cryptogram requests

| Mode | A replay returns |
| - | - |
| `inline`, while Guardian holds the cryptogram | The original response in full: token number, cryptogram or dynamic CVV, ECI, expiry, type and metadata. |
| `inline`, after that | The original status and the keys the original response had, with `number` and `cryptogram` or `dynamic_cvv` set to `null`. ECI, expiry, type and metadata are kept. |
| `reference` | The original `cryptogram_reference` and its `expires_at`, also after the reference was forwarded or expired. A forward with it is refused as usual. |

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

| Wallet | A replay returns |
| - | - |
| Apple Pay | The wallet token as [Tokenize Apple Pay](https://developer.hellgate.io/products/guardian/api-reference/wallet/tokenize-apple-pay.md) renders it now: its ID, and the card's brand, last four digits and expiry. |
| Google Pay | The wallet token as [Get wallet token](https://developer.hellgate.io/products/guardian/api-reference/wallet/get-wallet-token-details.md) renders it now. |

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:

| You send again | Apple Pay | Google Pay |
| - | - | - |
| A payload whose wallet token exists | `200` with the original wallet token | `200` with the original wallet token |
| A payload whose wallet token has been deleted | `409` `APPLE_PAY_TOKEN_DELETED` | `409` `GOOGLE_PAY_DUPLICATE_PAYLOAD` |

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](https://developer.hellgate.io/products/guardian/api-reference/pci/forward-card-data.md), [Forward cryptogram](https://developer.hellgate.io/products/guardian/api-reference/network/forward-cryptogram.md) and [Forward wallet token](https://developer.hellgate.io/products/guardian/api-reference/wallet/forward-wallet-token.md). 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](#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.