---
title: Idempotent requests
description: Retry a write safely with the Idempotency-Key header.
---

{/* vale off */}

An idempotency key lets you retry a request that timed out or failed in transit without making its change twice. Tractorbeam follows the IETF's [Idempotency-Key HTTP Header Field](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) draft.

## Sending a key

Send the key in the `Idempotency-Key` header, as an [RFC 9651](https://www.rfc-editor.org/rfc/rfc9651#name-strings) String: the key in double quotes.

```sh
curl -X POST "https://<workspace>/api/v1/actions/sync-ledger/invoke?branch=main" \
  -H "Authorization: Bearer $TRACTORBEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"' \
  -d '{ "input": { "since": "2026-11-01" } }'
```

A key is 1 to 255 printable ASCII characters without spaces. Use a new random UUID for each request, and send the same key with each retry of that request.

## Operations that take a key

Every `POST` and `PATCH` takes a key, with two exceptions. A Query's call, `POST /api/v1/queries/{query}/invoke`, and `POST /api/v1/blobUrls` only read, so they take none. An operation whose response holds a secret, such as `POST /api/v1/apiKeys`, takes none either: keeping its response for a retry would keep the secret too. The [API reference](/docs/api-reference) lists the `Idempotency-Key` header on each operation that takes one. Tractorbeam's CLI and SDKs send a new key with each such request and the same key with each of its retries.

These operations require a key:

| Operation                                           | Key                           |
| --------------------------------------------------- | ----------------------------- |
| `POST /api/v1/branches/{branch}/apply`              | Required                      |
| `POST /api/v1/branches/{branch}/merge`              | Required                      |
| `POST /api/v1/changeRequests/{changeRequest}/merge` | Required                      |
| `PUT /api/v1/apps/{app}/deployment`                 | Required                      |
| `POST /api/v1/actions/{action}/invoke`              | Required                      |
| `POST /api/v1/workspace/archive`                    | Required                      |
| `POST /api/v1/functions/invoke`                     | Required for an Action's call |

A key belongs to the principal that sent it and the operation it sent it to: on the Branch the request writes, for `POST /api/v1/workspaces` in the Account, and otherwise in the Workspace the request addresses. Another principal's request with the same key is a different request.

## Retries

A retry that sends the same key and the same request, its path, query, and body, returns the first request's result without making its change again. Tractorbeam compares JSON bodies in their [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785) canonical form, so the order of an object's members doesn't matter.

Tractorbeam keeps the first successful response for 24 hours, and a retry within that time returns it. A request that failed keeps nothing, so its retry runs again. A write to a Branch, such as an Apply, a merge, a deploy, or an Action or Mutation call, also keeps its key with the change it made, so a later retry still makes no second change.

For `POST /api/v1/account/managers`, if a request is cut off after the invitation is sent but before its response is kept, a retry made more than a minute later can send the invitation again.

## Errors

| Status | `code` | When |
| --- | --- | --- |
| 400 | `INVALID_ARGUMENT` | The operation requires a key and the request sent none, or the key isn't a quoted string of 1 to 255 printable ASCII characters without spaces. |
| 409 | `ABORTED` | The first request with the key is still running. Retry the same request later. |
| 422 | `IDEMPOTENCY_KEY_REUSED` | An earlier request sent the key with a different request. Send the new request with a new key. |
