Idempotency

Idempotency allows safe API retry requests and has been made available for the endpoints:

  • POST /shipments

  • POST /registered-shipments

Including an Idempotency-Key header in requests to these POST endpoints makes them idempotent. This means our API prevents duplicate operations when you retry a request that failed due to a connection issue. You are able to retry the request using the same idempotency key with the guarantee that no more than one shipment is created and registered with the carrier.

Note

If a request with the same idempotency key has been processed in the last 24 hours, the response of that request will be replayed (same resource data or carrier error). Replays are indicated by the Idempotency-Replay header with value true on the response.

Warning

If a request with an idempotency key is posted while a previous request with the same idempotency key is still being processed, the response of that request will be 409 Conflict to avoid race conditions.

Creating an idempotency key

The value of the Idempotency-Key header should be a generated token unique to the request data. If you get a response with error code 4xx indicating validation issues, the idempotency key of the next request should reflect that the content has changed. If you use the same idempotency key after a response error, you will get the same error regardless of the changed data in the subsequent request.

Things to keep in mind when generating an idempotency key:

  • Use an algorithm that generates a token with enough uniqueness in a 24-hour time period (our system expires idempotency keys after 24 hours), for example a UUID v4.

  • If you are making a hash of the request data, keep in mind that generated timestamps (register_at) can cause the request data to never be the same, causing the idempotency key to also be different. Ignore these attributes when generating the idempotency key, or use 0 as the registration timestamp.

  • Idempotency keys can be up to 255 characters long. Larger values will be ignored and requests will be treated as if they had no idempotency key.