Skip to content

Idempotency

A write can fail after the server has already done the work: the connection drops, the response never arrives. Retried without protection, it would create a second shipment or a second invoice. The Idempotency-Key header prevents that.

Endpoint Without the header
POST /shipments (create a shipment) 400
POST /shipments/{id}/cancel (cancel a shipment) 400
POST /invoices (issue an invoice) 400

On every other write the header is accepted and works the same way.

  • The key is a unique string your client picks for one operation, for example a UUID v4 generated once and kept until the first response.
  • The key is kept for 24 hours, separately for each installation of an app, together with a fingerprint of the request.
  • Same key, same request: you get the first request's response (with Idempotent-Replayed: true), and the operation does not run again. Kept: a success (2xx) and a definitive refusal (4xx).
  • Not kept, so the same key runs the request again: a validation failure (422 validation_failed, for example an order_id not synced yet), a 429, a refusal whose code may pass later (errors) and any 5xx.
  • Same key, another body: 422. A key belongs to one operation only.
  • Same key while the first request is still running: 409. Retry after a pause.
Terminal window
# shipment.json: the request body, described in the reference
curl -X POST "https://api.connectato.com/v1/shipments" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f0c8a52-3b1e-4f7a-9d2c-6e8b1a4f7c30" \
-d @shipment.json

On a network error, a timeout, a 5xx or a code that may pass later, send the same request with the same key. If the first request was already processed, you get its response and the operation does not run a second time. Generate a new key only for a new operation.