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

# Idempotência

> Como usar o cabeçalho Idempotency-Key para retentativas seguras em qualquer endpoint de escrita da VMArea.

A API pública da VMArea suporta retentativas idempotentes no estilo Stripe em todo endpoint de escrita — assim, uma queda de rede ou travamento do cliente nunca deixa você na dúvida se aquele `POST` realmente foi executado.

## Como funciona

Envie um cabeçalho `Idempotency-Key` em qualquer requisição `POST`, `PUT`, `PATCH` ou `DELETE` para `/api/public/v1/*`. Reenvios da mesma chave pelo mesmo token de API retornam a resposta original — mesmo status, mesmo corpo — sem re-executar o endpoint.

| Aspecto             | Detalhe                                                               |
| ------------------- | --------------------------------------------------------------------- |
| Cabeçalho           | `Idempotency-Key`                                                     |
| Formato             | 1–255 caracteres ASCII imprimíveis (UUID4 recomendado)                |
| Aplica-se a         | Rotas de escrita `POST` / `PUT` / `PATCH` / `DELETE`                  |
| Janela de cache     | 24 horas a partir da resposta original                                |
| Marcador de reenvio | Resposta inclui `Idempotency-Replayed: true`                          |
| Reenvio simultâneo  | `409 Conflict` enquanto a primeira requisição ainda está em andamento |
| Respostas `5xx`     | NÃO são cacheadas — seguro renviar com a mesma chave                  |
| `GET`/`HEAD`        | Cabeçalho ignorado (esses métodos já são idempotentes por natureza)   |

## Escolhendo uma chave

Gere um novo valor por operação lógica — normalmente um UUID4 — e reutilize-o apenas ao reenviar exatamente aquela requisição. Use chaves diferentes para operações diferentes; use a mesma chave para retentativas da mesma operação.

## Exemplo com curl

```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"}'

# Queda de rede? Reenvie a *mesma* chave — você receberá a resposta original
# de volta, com `Idempotency-Replayed: true` nos cabeçalhos.
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"}'
```

## Ressalvas

<Note>
  A chave de cache é `(usuário do token de API, Idempotency-Key)`. Um token diferente da mesma conta é tratado como um chamador diferente.
</Note>

* Os corpos das requisições não são verificados por checksum — enviar um corpo diferente com uma chave reutilizada ainda retorna a resposta original. Mantenha uma chave por operação.
* Downloads binários (faturas em PDF etc.) estão fora do escopo: reenvios desses endpoints simplesmente re-executam a operação.
* A idempotência é melhor esforço. Se o nosso cache ficar brevemente indisponível, deixamos as requisições passar em vez de falhar; nessa janela rara, uma retentativa pode produzir um efeito colateral duplicado. Combine este cabeçalho com padrões defensivos normais para semântica verdadeira de "no máximo uma vez".