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}'
| Situation | Response |
|---|---|
| First time | processed normally |
| Same key and body, after it finished | the same response as the first time, with the Idempotent-Replayed: true header. Nothing is created again |
| Same key while the first is still running | 409 idempotency_in_progress, with Retry-After: 1 |
| Same key with another body or route | 422 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;
5xxand429responses are not stored, so you can retry;- it only applies to
POST.PATCHandDELETEcan 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:
- When reading an item (
GET /v1/.../{id}), keep the response'sETagheader, for exampleW/"a1b2c3…".POSTandPATCHalso return the newETag. - When updating or deleting, send that value in the
If-Matchheader. - If the item changed since you read it, the response is
412(precondition_failed), and theETagheader 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.