Retries and idempotency
Send an Idempotency-Key with every write. A retry then returns the first answer instead of doing the work twice, on both APIs, for 24 hours.
Networks drop answers, and scripts retry. Without protection, a retried POST creates a second
row. Send an Idempotency-Key header with every write, to an app or to the Studio:
curl -X POST "https://your-suite.gtable.app/your-app/v1/tables/tbl_8fj3kq2wmv5d/records" \
-H "Authorization: Bearer $GTABLE_TOKEN" \
-H "Idempotency-Key: 6f1c2b8e-1d2a-4f0e-9a51-2f1d7e0c3b44" \
-H "Content-Type: application/json" \
-d '{"records":[{"Name":"Imported row"}]}'What happens
| You send | You get |
|---|---|
| a new key | the request runs; its answer is kept for 24 hours |
| the same key, the same request, within 24 hours | the first answer again, with Idempotency-Replayed: true, and nothing runs |
| the same key with a different request | 409 conflict: a key names one request |
A key is any unique string up to 255 characters; a UUID per logical operation is the usual choice. Keys are scoped to the plane, the person and the operation, so two people can never collide.
Which calls take it
Every write the reference marks with an Idempotency-Key header. A PUT or a PATCH repeated
is already the same as once, so the Studio keeps no answer for those: sending the same one twice
is safe on its own.
Together with retries
- Retry
429,500and network failures with the same key and an increasing delay. - Do not retry
4xxanswers other than429: the request itself is wrong, and will be wrong again. - A write that succeeded with
warningsis a success. Do not retry it.