> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vmarea.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Use the Idempotency-Key header to safely retry write requests without creating duplicate resources.

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

```bash theme={null}
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

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

* 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.