# 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](/guides/guides-retries/) defines retryable failures; [Create shipment](/guides/reference-create-shipment/) defines body constraints.

## Related pages

- [Agent Benchmark Control 0922 Docs](../index.md)
- [Authentication and workspace scope](./guides-authentication.md)
- [Create shipment](./reference-create-shipment.md)
- [Legacy v1: 2025-02-01](./legacy-v1.md)
- [List shipments](./reference-list-shipments.md)
- [Pagination and recovery](./guides-pagination.md)
- [ParcelBench documentation](../guides.md)
- [Quickstart](./guides-quickstart.md)
- [Retention and undocumented policies](./guides-retention.md)
- [Retries and error handling](./guides-retries.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.