---
title: "Retries and idempotency"
description: "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."
canonical: "https://gtable.app/docs/api/idempotency"
updated: "2026-10-05"
---

# Retries and idempotency

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:

```bash
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`, `500` and network failures with the **same** key and an increasing delay.
- Do not retry `4xx` answers other than `429`: the request itself is wrong, and will be wrong
  again.
- A write that succeeded with `warnings` is a success. Do not retry it.