# Idempotent requests

Idempotency reduces duplicate operations when you retry a mutating request, for example, after a timeout or a network error. It does not guarantee that an operation runs exactly once. This is separate from deduplicating [webhook deliveries](https://api-docs.solidgate.com/api/v2/webhook-signatures), which use the `event_id` field instead.

To make a request idempotent, send an `Idempotency-Key` header with a unique value for each distinct operation. The key is scoped to your account, endpoint, and environment, so the same key sent to a different endpoint or environment does not count as a reuse.

**Generate idempotency keys**

Generate a new key for each new operation. Do not reuse a key across different operations, and do not base a key on a business identifier, such as an order ID or invoice ID. One draft invoice can have multiple updates, such as setting the customer’s email and then correcting it. If both requests use the invoice ID as the key, the second request has a different body but reuses the same key. The API returns a `422` error and does not apply the update. A version 4 universally unique identifier (UUID) is a good choice.

An idempotency key is a string of 1 to 255 printable ASCII characters. Spaces and control characters are not valid and return a `400` error.

Idempotency support varies by endpoint. Send the request with an `Idempotency-Key` header and check the `Idempotency-Status` value. A value of `ignored` means the endpoint does not support idempotency.

If a request fails due to a network error or a timeout and the outcome is unclear, retry it with the same idempotency key. The original request might have already completed, so the retry returns the saved result instead of running the operation again.

**Response behavior**

Each response to a request sent with an `Idempotency-Key` header includes an `Idempotency-Status` header. The value describes how the key was handled.

Value
Description
stored
The request ran, and the result is saved under this key for future replay.
replayed
The response is a replay of a previous request with the same key.
not-stored; reason=unavailable
The idempotency feature was unavailable, so the API ran the request without idempotency protection.
ignored
The endpoint does not support idempotency. The key has no effect on the request.
`not-stored` includes a `reason` parameter, for example `not-stored; reason=unavailable`.

Stored and replayed responses also include `Idempotency-Created-At` and `Idempotency-Expires-At` headers. These report the timestamp of the first request and the time the saved result expires.

A saved result expires 24 hours after the first request. After this period, the API treats the same key as new.

A replayed response includes the original status code, body, `Content-Type` header, and `Location` header. Other headers might differ from the original response.

If a request fails validation or authentication before the API registers the idempotency key, the response does not include an `Idempotency-Status` header. Retry the request after you resolve the issue.

**Conflicts and errors**

A request returns `409 IDEMPOTENCY_KEY_IN_USE` when a request with the same key is still in progress. It returns `422 IDEMPOTENCY_KEY_REUSED` when the same key is reused on the same endpoint with a different request body. Both codes are listed in [error handling](https://api-docs.solidgate.com/api/v2/errors).

The API compares request bodies as parsed JSON, so differences in field order or whitespace do not trigger this error.

A `409` response includes a `Retry-After` header indicating how long to wait before you retry with the same key.

A client-side timeout or network error does not use the key. Retry the request with the same key. If the original request is still in progress, the retry returns `409 IDEMPOTENCY_KEY_IN_USE`. If the original request already completed, the retry returns the saved result.

The API saves and replays a `5xx` response like any other response, for up to 24 hours. Check the resource state before you retry, then retry with a new key only if the operation still needs to run.

Authentication errors (`401`/`403`) and request validation errors (`400`) happen before the API registers the key. Fix the request, then retry with the same key.

Other error responses register the key and are replayed on retry. Use a new key to run the operation again with different input.

**Idempotency is best effort**

Idempotency reduces duplicate operations caused by retries, but it does not guarantee that an operation runs exactly once. In rare cases, retrying a request with the same idempotency key can run the operation again:

- The idempotency feature is temporarily unavailable. The API does not record the key. The response includes `Idempotency-Status: not-stored; reason=unavailable`.
- The original request fails or takes unusually long before its result is saved. The operation might have taken effect before the failure or delay interrupted processing.


To reduce the risk of duplicate operations:

- If you receive a `409` response with code `IDEMPOTENCY_KEY_IN_USE`, wait for the duration specified in the `Retry-After` header, then retry with the same key. The original request might still be processing.
- If you receive no response, the outcome is unknown. Check whether the operation took effect before you retry. If you retry, use the same key.
- If the response includes `Idempotency-Status: not-stored`, idempotency protection did not apply to the request. Check whether the operation took effect before you submit it again.
- If the response includes `Idempotency-Status: stored` or `replayed`, the API saved the result of the original request, including errors. Check the HTTP status. If it is an error, check the resource state, then send the request with a new key.
- When duplicates would be costly, also set a business reference such as the `merchant_reference` [field](https://api-docs.solidgate.com/api/v2/subscriptions/create-subscription#subscriptions/create-subscription/t=request&path=merchant_reference), if the endpoint supports one, and look up records by it before you create a new one.


**Idempotency and business references**

Idempotency deduplicates based on the `Idempotency-Key` header alone, and the key is valid for 24 hours. Invoices and subscriptions also support a business reference field, such as `merchant_reference`, for longer-term deduplication. Use this field to look up or deduplicate records by your own identifiers, independent of the idempotency key.

▸
Idempotency example
This example illustrates how idempotency works when creating a subscription.

**1. Create a subscription with a key**

```http
POST /v2/subscriptions/create
Idempotency-Key: 9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d

{
  "customer_id": "cust_01KMG2ABYPF6XS5DMJQ817C429",
  "payment_instrument_id": "pi_01J1Z2X3Y4W5V6U7T8S9R0",
  "line_items": [{ "product_price_id": "e6f26db1-f633-4723-ab08-50ddee7bc648", "quantity": 1 }]
}
```

**2. Request times out. Retry with the same key and request body**

```http
HTTP/1.1 200 OK
Idempotency-Status: replayed
Idempotency-Created-At: 2026-10-24T11:45:00Z
Idempotency-Expires-At: 2026-10-25T11:45:00Z

{ "id": "subs_01HYDYBRKN16B8X3BR9WP78ZR7", "status": "ACTIVE" }
```

**3. Reuse the same key with a different request body**

```http
HTTP/1.1 422 Unprocessable Entity

{ "code": "IDEMPOTENCY_KEY_REUSED", "message": "idempotency key already used with a different request" }
```

**4. Retry while the first request is still in progress**

```http
HTTP/1.1 409 Conflict
Retry-After: 1

{ "code": "IDEMPOTENCY_KEY_IN_USE", "message": "a request with this idempotency key is still in process" }
```

**5. Send a request with an invalid idempotency key**

```http
HTTP/1.1 400 Bad Request

{
  "code": "VALIDATION",
  "message": "request validation failed",
  "context": {
    "constraints": {
      "Idempotency-Key": { "type": "FORMAT", "message": "must be 1 to 255 printable ASCII characters" }
    }
  }
}
```

**6. Request is rejected before processing (`400` body validation, `401`, `403`)**

The response has no `Idempotency-Status` header, and the API does not save the key. Fix the request, then send it again with the same key.

**7. Processing finishes with an error (`4xx` business errors such as `422 CUSTOMER_NOT_FOUND`, and `5xx`)**

The error is saved like a success: `Idempotency-Status: stored`, and retries with the same key return `replayed` for 24 hours. To try again, check the resource state, then send the request with a new key.

**8. Response is not saved**

```http
HTTP/1.1 200 OK
Idempotency-Status: not-stored; reason=unavailable
```

**9. Key expires (after `Idempotency-Expires-At`)**

After the time specified by `Idempotency-Expires-At`, the key can be used again. A request with that key is treated as a new request.

For help, contact us.