Retries and idempotency
Use the Idempotency-Key header on POST writes so retried requests replay the original result safely for 24 hours without duplicates.
Networks drop responses and automation scripts retry. Passing an Idempotency-Key header prevents duplicate record creations or side effects when a POST request is retried.
curl -X POST "https://your-suite.grid82.app/your-app/v1/tables/tbl_8fj3kq2wmv5d/records" \
-H "Authorization: Bearer $GRID82_TOKEN" \
-H "Idempotency-Key: 6f1c2b8e-1d2a-4f0e-9a51-2f1d7e0c3b44" \
-H "Content-Type: application/json" \
-d '{"records":[{"Name":"Meridian Annual Support","Amount":24000}]}'Idempotency rules
| Scenario | Server behaviour |
|---|---|
First time seeing Idempotency-Key | Executes request and caches response for 24 hours |
| Same key + identical request body within 24 hours | Returns original response with header Idempotency-Replayed: true without re-executing |
| Same key + different request method, path, or body | Rejects with 409 conflict |
- Key format. Any unique string up to 255 characters (a UUID per logical operation is recommended). Keys are scoped by plane, caller, and operation.
- Permission check on replay. Cached responses verify that the caller’s rights still cover the replayed answer before returning it.
- Methods.
POSTendpoints documented withIdempotency-Keysupport replay caching. RepeatingPUT,PATCH, orDELETEis already idempotent on its own.
Retry strategy
- Do retry.
429(rate_limited),500(internal), and network timeouts, using exponential backoff and the sameIdempotency-Key. - Do not retry.
400/422validation errors,401/403/404authorization errors,402quota errors, or2xxsaves that succeeded withwarnings.