Idempotency

Networks fail. Your server may create a delivery successfully but lose the response before it reaches you. If you simply send a fresh create request, you could create two deliveries. An idempotency key solves this. Think of it as a receipt number for one action: “create order 1842.” When HaulStow sees the same receipt number and the same request again, it returns the first result.

When it is required

Send an Idempotency-Key header on these requests:

POST /recipients
POST /recipients/{recipient_id}/addresses
POST /deliveries
POST /deliveries/bulk
POST /test-helpers/deliveries/{delivery_id}/transition
POST /test-helpers/deliveries/{delivery_id}/simulate

Cancellation already has the same outcome when repeated, but it also accepts the header so your code can use one rule for every mutation. GET requests and quote requests do not need it.

Idempotency-Key: shop-order-1842-create-v1

The value must contain 8–255 characters. A UUID is a good default:

Node.js

import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID();

You can also derive it from an ID that is already unique in your system:

checkout_1842_create_delivery_v1

Save the value with your local order or job. HaulStow retains it for 24 hours.

The rule that prevents mistakes

Use:

the same key when retrying the same HTTP method, URL, environment, and JSON body;
a new key for a new action or any changed request body.

Do not use one global key for every request.

curl --request POST "$HAULSTOW_BASE_URL/deliveries" \
  --header "Authorization: Bearer $HAULSTOW_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: checkout_1842_create_delivery_v1" \
  --data @delivery.json

If the connection times out, run that exact command again. Do not invent a new key while the first result is unknown.

Bulk requests

One Idempotency-Key covers a whole POST /deliveries/bulk request. HaulStow stores the complete response, including any items that failed, and replays it when you retry with the same key and body. Retrying with the same key therefore never re-attempts a failed item. To retry only the failed items, send a new bulk request that contains just those items, with a new key. Put an external_id on every item so you can match each result to your own records.

Retry behavior

Situation	Result
What happened	What HaulStow returns	What your code should do
---	---	---
Same key + same request already finished	The original status and body, plus `Idempotent-Replayed: true`	Treat it exactly like the original response.
Same key + different request	`409 IDEMPOTENCY_CONFLICT`	Fix the bug: use the old body or a new key for the changed action.
The first request is still running	`409 IDEMPOTENCY_IN_PROGRESS` plus `Retry-After`	Wait for the number of seconds in `Retry-After`, then retry unchanged.
A required key is missing	`400 IDEMPOTENCY_KEY_REQUIRED`	Add a unique `Idempotency-Key` header.

Authentication and validation failures are not stored because no mutation was attempted. Deterministic failures after a mutation claim may be stored to prevent repeated side effects.

What a replay looks like

The JSON is the same as the original response. This response header tells you it was replayed:

Idempotent-Replayed: true

You usually do not need special business logic for a replay. If the status and response body indicate success, handle them as success.

A safe retry checklist

Before retrying a create request, confirm that you kept all four things unchanged:

The sandbox or live base URL.
The HTTP method and path.
The JSON request body.
The Idempotency-Key value.

Get started

Core concepts

Endpoint reference

When it is required

The rule that prevents mistakes

Bulk requests

Retry behavior

What a replay looks like

A safe retry checklist

​When it is required

​The rule that prevents mistakes

​Bulk requests

​Retry behavior

​What a replay looks like

​A safe retry checklist

When it is required

The rule that prevents mistakes

Bulk requests

Retry behavior

What a replay looks like

A safe retry checklist