Timeout does not mean failure
A client can send a create request, the service can commit it, and the response can disappear in transit. From the client’s point of view the result is unknown. Retrying is sensible — but without idempotency, the retry may create a second folder, share or webhook registration.
An idempotency key gives the logical request a stable identity across retries.
The same request should return the same resource
When a create request is retried with the same key and same effective payload, the service can replay the original result rather than repeating the mutation. That keeps workspace state and audit history aligned with the user’s intent: create one thing.
Conflicting reuse of the key should be an explicit error rather than an invitation to guess.
Idempotency is an operations feature
This is not merely an API nicety. Duplicate folders, repeated shares or multiple webhook registrations create real support and governance problems. Reliable create semantics reduce those failures before they reach users.
They also make client code simpler because ordinary retry strategies can be used without inventing bespoke reconciliation for every resource.
Retry with the same key
Give the create a stable idempotency key and confirm a lost response still returns the original object. Duplicate folders after a timeout are an API design problem, not an operator mistake.