DigitalOcean API v2 and HTTP client retry: how to avoid duplicate droplet creation

Question

Goal
Design a retry strategy for POST /v2/droplets that guarantees at most one droplet is created, even when the client automatically resends a failed request.
Constraints

DigitalOcean’s v2 REST API does not expose idempotency headers for droplet creation.
Rate‑limit responses (429) include a Retry‑After header but do not indicate whether the write has been recorded.
Duplicate name attempts may return 409 Conflict, but the behavior is not guaranteed for all duplicate scenarios.
Client‑side deduplication relies on name uniqueness or pre‑checking the droplet list, both of which can fail in race conditions.

Unresolved Decision
Without an API‑level idempotency key, the community must decide how a client can safely retry a droplet creation without causing double charges or orphaned resources.
Specific Questions

Does DigitalOcean plan to introduce an idempotency key for POST /v2/droplets, and if so, what header or query parameter would be used?
In the absence of API‑level support, what client‑side patterns (e.g., unique name generation, pre‑query checks, or idempotent transaction IDs) are recommended to collapse duplicate creation attempts?
How should a client interpret a 409 Conflict response to ensure that a retry does not result in a second droplet, especially when name collisions are possible due to case insensitivity?

Tasadduq Burney · Answer

Answer
To guarantee at most one droplet is created despite automatic retries, persist a unique creation intent before the POST, then after any failure list droplets by that intent and act accordingly.
Likely explanation
DigitalOcean’s v2 API offers no idempotency key or guaranteed 409 signal, so a blind retry can cause a second droplet. The safe approach is to make the client’s intent durable and reconcile state after each attempt.
Confirmed facts (from research)

POST /v2/droplets has no documented idempotency header.
429 responses include Retry‑After but do not indicate whether the write succeeded.
409 Conflict on duplicate names is not reliable for all collision cases, including case‑insensitive matches.
Listing droplets by a unique name or tag is eventually consistent; a short wait or retry of the list may be needed.

Generate a unique identifier for the intended droplet (e.g., a UUID) and derive a droplet name or tag from it that no other process will use.
Persist this identifier (and the derived name/tag) in durable storage before sending the POST.
Send the POST /v2/droplets request.
On any non‑2xx response (including timeout, connection reset, 429, 5xx, or even 2xx if you want to be extra safe):

Wait for any Retry‑After if present.
List droplets filtered by the persisted name/tag (using the API’s name query parameter or tag filter).
If exactly one droplet matching the identifier exists, treat the operation as successful and stop retrying.
If none exist, you may safely retry the POST (go back to step 3).
If more than one exists, investigate a possible collision; abort and manual cleanup is required.

Optionally, after a successful creation, record the droplet ID alongside the intent for future reference.

Diagnostic detail that changes the recommendation: Can your application durably store the creation intent before the POST? If not, you must rely on an asynchronous reconciler that periodically checks for stray droplets instead of a synchronous retry loop.

DigitalOcean API v2 and HTTP client retry: how to avoid duplicate droplet creation

Goal

Constraints

Unresolved Decision

Specific Questions

1 answer

Answer

Likely explanation

Confirmed facts (from research)

Your perspective belongs here.

0 question comments