> For the complete documentation index, see [llms.txt](https://docs.licensespring.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.licensespring.com/license-api/consumption/retrying-consumption-calls-safely.md).

# Retrying Consumption Calls Safely

A network error or a timeout can leave your application unsure whether a consumption was recorded. Retrying blindly can record the same usage twice. Send an `Idempotency-Key` header with each consumption call, and you can retry that call as often as you need: LicenseSpring records it once.

This works on [Add Consumption](https://docs.licensespring.com/license-api/consumption/add-consumption) (`POST /api/v4/add_consumption`) and [Add Feature Consumption](https://docs.licensespring.com/license-api/consumption/add-feature-consumption) (`POST /api/v4/add_feature_consumption`).

### Sending a key

1. **Create a new key for each consumption you want to record.** Use a random value such as a UUID. The key can be up to 255 characters.
2. **Send it in the `Idempotency-Key` header** with the request.
3. **If the call fails with a network error or a timeout, send the exact same request again with the same key.**
4. **Create a new key for the next consumption**, even if it has the same amount and goes to the same license.

```bash
curl --location --request POST '/api/v4/add_consumption' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Date: string' \
--header 'Authorization: string' \
--header 'Idempotency-Key: 3f9a6c1e-8d2b-4e7f-a5c0-1b2d3e4f5a6b' \
--data-raw '{
  "hardware_id": "demo-device-01",
  "product": "consumption-demo",
  "license_key": "DEMO-AAAA-BBBB-CCCC",
  "consumptions": 5
}'
```

### What a retry returns

| Situation                                        | What LicenseSpring does                                       | Response                                                                             |
| ------------------------------------------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| First call with this key                         | Records the consumption and sends its events and emails       | `200`, the new totals                                                                |
| Same key again, within one hour                  | Records nothing, sends no events or emails                    | `200`, the exact response of the first call, including its `LicenseSignature` header |
| Same key again, after one hour                   | Records nothing, sends no events or emails                    | `200`, the license's or feature's current totals                                     |
| Several calls with the same key at the same time | Records the consumption once                                  | `200` for all of them                                                                |
| The first call failed with an error              | Nothing was recorded, so the retry is processed as a new call | The result of the retry                                                              |

{% hint style="warning" %}
**A key stands for one consumption, not for a request body.** LicenseSpring does not compare the body of a retry with the first call. If you reuse a key for a different amount, or for a different license or feature within the hour, you get the first call's response back and the new consumption is not recorded. Always create a new key for new usage.
{% endhint %}

### Things to know

* **The key is optional.** Calls without it work as before, and each call is recorded.
* **Limits are enforced exactly, also under load.** Many parallel calls against the same license, feature or pool never take the total past its limit. The calls that would go past it fail with `license_not_enough_consumptions`, `feature_not_enough_consumptions` or `pool_quota_exhausted`.
* **A replay is always a `200`.** Error responses are not stored, so a retry after an error is a new attempt.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.licensespring.com/license-api/consumption/retrying-consumption-calls-safely.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
