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

# Idempotência

> Como usar Idempotency-Key para retries seguros em criação e atualização de pedidos.

Use `Idempotency-Key` em chamadas que podem ser repetidas pelo seu backend por timeout, instabilidade de rede ou retry do gateway.

## Como enviar

```http theme={null}
Idempotency-Key: order_001_create
```

Use uma chave única por operação lógica:

* criação do pedido: `order_001_create`
* confirmação de pagamento: `order_001_paid`
* reembolso: `order_001_refunded`

## O que acontece no replay

Com a mesma chave, mesmo endpoint e mesmo dashboard, a Atriby retorna a resposta cacheada.

Exemplo: se `POST /api/v1/orders` criou o pedido com status `201`, uma repetição com a mesma chave retorna o mesmo corpo/status cacheado.

## TTL

Registros de idempotência expiram em 24 horas. Depois disso, a chamada pode ser processada novamente.

## Limitação atual

No MVP atual, a criação/atualização do pedido e a gravação do cache de idempotência ainda não ficam na mesma transação de banco. Isso significa que uma falha muito específica entre gravar o pedido e gravar o cache pode exigir retry cuidadoso pelo cliente.

Na prática:

* Sempre envie `Idempotency-Key` desde a primeira tentativa.
* Use `externalId` estável no pedido.
* Trate `DUPLICATE_EXTERNAL_ID` como sinal para consultar o pedido existente antes de reenviar a criação.