Idempotency - VMArea Developer Docs

The VMArea Public API supports Stripe-style idempotent retries on every write endpoint, so a network blip or client crash never leaves you wondering whether a POST actually went through.

How it works

Send an Idempotency-Key header on any POST, PUT, PATCH, or DELETE request to /api/public/v1/*. Replays of the same key by the same API token return the original response — same status, same body — without re-executing the endpoint.

Aspect	Detail
Header	`Idempotency-Key`
Format	1–255 ASCII printable characters (UUID4 ideal)
Applies to	`POST` / `PUT` / `PATCH` / `DELETE` write routes
Cache window	24 hours from the original response
Replay marker	Response carries `Idempotency-Replayed: true`
Concurrent replay	`409 Conflict` while the first request is still in flight
`5xx` responses	NOT cached — safe to retry with the same key
`GET` / `HEAD`	Header ignored (these are already idempotent)

Picking a key

Generate a fresh value per logical operation — typically a UUID4 — and reuse it only when retrying that exact request. Use different keys for different operations; use the same key for retries of the same operation.

Example

KEY=$(uuidgen)

curl -X POST https://api.vmarea.com/api/public/v1/vms \
  -H "x-api-key: $VMAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"name":"web-01","planId":"plan_xxx","regionId":"sin-1","osTemplateId":"tpl_ubuntu_24"}'

# Network glitch? Replay the same key — you'll get the original response
# back, with Idempotency-Replayed: true in the headers.
curl -X POST https://api.vmarea.com/api/public/v1/vms \
  -H "x-api-key: $VMAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"name":"web-01","planId":"plan_xxx","regionId":"sin-1","osTemplateId":"tpl_ubuntu_24"}'

Caveats

The cache key is (API token user, Idempotency-Key). A different token from the same account is treated as a different caller.

Request bodies are not checksummed — sending a different body with a reused key still returns the original response. Keep one key per operation.
Binary downloads (PDF invoices, etc.) are out of scope: replays of those endpoints will re-execute.
Idempotency is best-effort. If the cache is briefly unavailable, requests are let through rather than failed; in that rare window a retry may produce a duplicate side effect. Pair this header with normal defensive patterns for true at-most-once semantics.