For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 (POST /api/v4/add_consumption) and 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.

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

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.

Last updated

Was this helpful?