Skip to main content

Concurrency and idempotency

Retrying a POST without duplicates: Idempotency-Key​

When a request takes too long or the connection drops, you do not know whether the item was created. To retry safely, send the Idempotency-Key header on POST requests:

curl -X POST https://api.validades.com/v1/batches \
-H "Authorization: Bearer vld_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1234-batch-1" \
-d '{"product_id": "…", "exp_date": "2026-12-31", "amount": 12}'
SituationResponse
First timeprocessed normally
Same key and body, after it finishedthe same response as the first time, with the Idempotent-Replayed: true header. Nothing is created again
Same key while the first is still running409 idempotency_in_progress, with Retry-After: 1
Same key with another body or route422 idempotency_key_reused

Rules:

  • the key has up to 255 characters: letters, numbers and _ - : .;
  • it is kept for 24 hours and only applies to the same API key;
  • 5xx and 429 responses are not stored, so you can retry;
  • it only applies to POST. PATCH and DELETE can already be repeated without duplicate effects.

Use a value that identifies the operation in your system, for example the order and item ids.

Alternative: send the id field (a UUID you generate) in the POST. If the item already exists, the response is 409 conflict, and nothing is duplicated.

Not overwriting changes: ETag and If-Match​

The same data may be changed at the same time by your integration and by someone on the team in the app. To avoid wiping out the other person's change without noticing:

  1. When reading an item (GET /v1/.../{id}), keep the response's ETag header, for example W/"a1b2c3…". POST and PATCH also return the new ETag.
  2. When updating or deleting, send that value in the If-Match header.
  3. If the item changed since you read it, the response is 412 (precondition_failed), and the ETag header carries the current version. Read the item again and decide what to do.
curl -X PATCH https://api.validades.com/v1/batches/BATCH_ID \
-H "Authorization: Bearer vld_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H 'If-Match: W/"a1b2c3d4e5"' \
-d '{"amount": 10}'

If-Match: * accepts any version. Without If-Match, the change is always applied.

Saving requests: If-None-Match​

When fetching an item you already have, send the saved ETag in If-None-Match. If nothing changed, the response is 304 Not Modified, with no body.

GET /v1/products/{id}?include=batches has no ETag, because a change to a batch does not change the product version.

The app works offline​

The team's devices may go offline and send their changes later. When the same data is changed through the API and on a device before they sync, the last change received may win. For data the team also changes in the app, prefer using If-Match.