Use idempotency keys, client references, and replay-safe lookup patterns to prevent duplicate carrier writes.
Native Keys vs Your Own Deduplication Ledger
Some carriers accept an Idempotency-Key or client transaction ID and promise to replay the original result when the same logical write arrives again. Others give you no help at all. In both cases, your system still needs a durable operation key that ties the write, the expected side effects, and the observed result together.
Client References Resolve Ambiguous Writes
When a create call times out, the safest recovery path is usually: search by your client reference, inspect the existing shipment if it exists, and only retry when you can prove the original write never landed. This is what turns a timeout from guesswork into deterministic recovery.
Carrier Reality
DHL Express and similar APIs may expose shipment or pickup identifiers differently across endpoints. If your write path and your lookup path do not share the same client reference strategy, your deduplication design falls apart under pressure.
Idempotency Is Also an Operations Contract
The operation key must show up in logs, support tooling, and incident runbooks. If support cannot search by it, or if your retry worker cannot correlate it to the original attempt, you still have a duplicate-label problem waiting to happen.