Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Idempotent requests

Retry a write safely with the Idempotency-Key header.

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 draft.

Sending a key

Send the key in the Idempotency-Key header, as an RFC 9651 String: the key in double quotes.

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 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 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.

Last updated on