Skip to content

Idempotency

A network error or a timeout can leave you unsure whether a write happened. An Idempotency-Key header lets you send the same write again without doing it twice.

These routes accept the header:

  • POST /shipments
  • POST /shipments/:id/confirm
  • POST /shipments/:id/cancel
  • POST /shipments/:id/retry
  • POST /shipments/:id/not-received

Use a new key, for example a UUID, for each action you take, and store it with the action. When you retry that action after a timeout or a 5xx answer, send the same key.

Idempotency-Key: 3a7c1f0e-6b2d-4e8a-9c5f-1d2e3f4a5b6c

The key is 8 to 255 characters. A shorter or longer key answers 400.

  • A repeat with the same key on the same route, within 24 hours, returns the first successful answer with the same status code. Tujyane does not do the work again.
  • Tujyane does not compare the bodies. Never reuse a key for a different request.
  • While the first request with a key is still running, a repeat answers 409 REQUEST_IN_PROGRESS. Wait, then retry with the same key.
  • Tujyane does not store failed answers. A retry after a 4xx answer runs the request again.
  • A key applies only to your account, the mode of your API key, and the route.
  • A repeated create makes a second Shipment.
  • A repeated cancel answers 409 ILLEGAL_SHIPMENT_TRANSITION.
  • A repeated confirm returns the current state and does nothing else.