Idempotency and retries
The Deel API supports the Idempotency-Key header so that a retried request does not create a second record. The CLI attaches this header to every mutating request automatically and uses it to retry transient failures.
Derived idempotency keys
For every POST, PUT, PATCH, and DELETE request, the CLI derives a UUID version 5 key from a canonical form of the request: the method, the path, the query parameters, and the body with object keys sorted. Re-running the identical command produces the identical key, and the API returns the original result instead of creating a duplicate.
Because the key is derived from the content, two commands that differ in any field produce different keys. A command that intentionally creates a second identical record must supply its own key.
For multipart uploads the key is derived from the text fields plus each file’s name and size, not the file bytes.
Supplying your own key
--idempotency-key <value> replaces the derived key. Use it when you want a fresh attempt for a body that was already accepted, or when your own system already tracks an idempotency key per operation.
The key is also available in the local log entry of the request under idempotency_key, so an operator can correlate a CLI run with the API’s view of the request.
Retry policy
Which failures the CLI retries automatically:
The CLI makes up to three attempts. When the response carries a Retry-After header, the CLI waits for that many seconds; otherwise it backs off exponentially starting at 200 ms. After the last attempt the response is returned as is and, for error statuses, mapped to the error envelope.
Retries are safe for mutating requests only because the same idempotency key is sent on every attempt. Passing --idempotency-key does not change this: the CLI reuses your key across its own retries.
Relationship to the API
The CLI follows the API’s idempotency semantics. Keys are scoped by the API in the same way as for any other client, so a key sent by the CLI and the same key sent by your application refer to the same request.