---
title: "Retries and idempotency"
description: "Use the Idempotency-Key header on POST writes so retried requests replay the original result safely for 24 hours without duplicates."
canonical: "https://grid82.com/docs/developers/rest/idempotency"
updated: "2026-11-20"
---

# Retries and idempotency

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.

```bash
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.** `POST` endpoints documented with `Idempotency-Key` support replay caching. Repeating `PUT`, `PATCH`, or `DELETE` is already idempotent on its own.

## Retry strategy

- **Do retry.** `429` (`rate_limited`), `500` (`internal`), and network timeouts, using exponential backoff and the **same** `Idempotency-Key`.
- **Do not retry.** `400`/`422` validation errors, `401`/`403`/`404` authorization errors, `402` quota errors, or `2xx` saves that succeeded with `warnings`.
