Idempotency

The Carriyo API supports idempotency for safely retrying write requests without performing the same operation twice. Write endpoints accept an optional Idempotency-Key request header.

Provide a unique key that identifies each logical operation — for example, a UUID. If your integration layer retries the call after a client timeout, a dropped connection, or any outcome where you did not receive a definitive response, send the same key with the same payload. Carriyo stores the response and returns it on subsequent matching requests.

Reuse a key only when retrying that exact operation with the same body. Generate a new key for each distinct operation.

Request header

Header	Required	Description
`Idempotency-Key`	No	A client-generated unique value (for example, a UUID) that identifies one logical operation. Reuse the same key only when retrying that exact operation with the same payload.

Response header

Header	When present	Description
`Idempotent-Replayed`	Replayed responses only	Set to `true` when Carriyo returns a stored response for a prior request with the same key, rather than executing the operation again.

Omit Idempotency-Key and the request is processed normally — the header is never required.

How it works

Scoped per endpoint. A key is unique within your tenant for that specific operation. The same key on create shipment and cancel shipment are independent.
Payload must match. The fingerprint includes the HTTP method, path, query string, and request body. Reusing a key with a different body returns 422.
In-flight protection. A concurrent retry while the first call is still running returns 409.
Replays are exact. The stored HTTP status and body are returned unchanged, including 4xx responses. Generate a new key for each distinct operation; keep the same key only when retrying that operation.
TTL. Stored responses expire after 12 hours.

Scenario

Client timeout on shipment create

Your integration posts POST /shipments with Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7 and partner_shipment_reference: SHP-10042.
Carriyo creates the shipment and begins the response, but the HTTP connection times out before your client reads it. You cannot tell whether the shipment exists.
Your retry policy resubmits the same request with the same key and body.
Carriyo returns the stored 201 response with Idempotent-Replayed: true. No duplicate shipment is created.

Without the key, step 3 would be a new create attempt. If the original call had succeeded, the retry would fail on the duplicate partner_shipment_reference instead of returning the original result.

What this is not

Idempotency-Key is a request-replay mechanism for uncertain network outcomes. It is separate from entity-level idempotency enforced through partner reference fields.

Carriyo also guards against duplicate entities through tenant-scoped partner references:

Shipments — partner_shipment_reference must be unique. Submitting the same reference again returns 400; it does not return the existing shipment.
Orders — partner_order_reference must be unique. Submitting the same reference again returns 400; it does not return the existing order.

These fields identify your entity in your system. They prevent accidental duplicates when you issue two independent create calls with the same reference. They do not replay a stored HTTP response the way Idempotency-Key does.