Idempotency

Idempotency-Key is required for POST /v2/shipments. Use a unique key for each logical shipment creation. The server retains the key and request fingerprint for 36 hours from the first accepted request. Keys are scoped to the workspace and operation.

Retrying the same key with an identical body during that window returns the original response with Idempotency-Replayed: true and creates no second shipment. Reusing the key with a different body returns HTTP 409 idempotency_conflict. A retry after a network timeout must keep both key and body unchanged. Do not generate a new key simply because the first response was lost.

After 36 hours, a key may be treated as a new request. Reconcile the external_ref before submitting again outside the retention window. external_ref is an application reference, not a server-side uniqueness guarantee. Retries defines retryable failures; Create shipment defines body constraints.