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

# Idempotência

> Repita uma requisição com segurança: a mesma chave devolve a mesma resposta, sem disparar nem cobrar de novo.

Um sistema que perde a resposta por timeout costuma reenviar a requisição. Sem proteção, um `POST` repetido cria um item duplicado ou dispara o mesmo alerta duas vezes, cobrando duas vezes. O header `Idempotency-Key` resolve isso.

## Onde usar

Em duas rotas, e só nelas:

* `POST /establishments/{establishment}/items`
* `POST /establishments/{establishment}/items/{item}/events`

O header é opcional, mas recomendamos enviá-lo sempre nas duas.

## Como usar

Gere um valor único para **cada operação que você pretende fazer** (um UUID v4 serve) e envie-o em `Idempotency-Key`. O valor tem de 1 a 255 caracteres ASCII visíveis. Em caso de falha de rede, repita a requisição **com a mesma chave e o mesmo corpo**.

```bash theme={null}
curl -X POST "$API/establishments/12/items/42/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f" \
  -d '{ "message": "Chegou!" }'
```

## O que acontece

* A **primeira resposta** fica guardada por **24 horas**: tanto um sucesso (2xx) quanto uma **recusa de regra**, isto é, qualquer erro com `code` próprio, como `insufficient_credits`, `dispatch_in_progress` ou `dispatch_too_soon`.
* Uma repetição com a mesma chave e o mesmo corpo recebe a resposta guardada, byte a byte, com o header **`Idempotent-Replayed: true`** e o `Content-Language` original. Nada é processado de novo e nada é cobrado de novo.
* Uma recusa guardada **não é tentada de novo**. Para tentar de verdade (por exemplo, depois de comprar créditos), envie uma chave nova.
* `validation_failed`, `forbidden` e erros de servidor (5xx) **não** são guardados: corrija e repita, com a mesma chave se quiser.
* A repetição conta no limite de requisições (veja [Convenções](https://docs.needalert.app/api/conventions.md)).

> [!NOTE]
>
> Guardar também as recusas de regra é diferente do que fazem algumas APIs de pagamento, que só guardam sucessos. Aqui, uma recusa como `dispatch_too_soon` repetida com a mesma chave continua recusada mesmo depois que os segundos passaram: use uma chave nova.

## Erros do próprio header

| HTTP | `code` | Causa |
| - | - | - |
| 422 | `idempotency_key_reused` | A mesma chave foi usada com um corpo diferente. Cada operação pretendida tem a sua chave. |
| 409 | `idempotency_request_in_progress` | A primeira requisição com esta chave ainda está sendo processada. Aguarde um instante e repita. |
| 422 | `validation_failed` (campo `idempotency_key`) | O valor está vazio, passa de 255 caracteres ou tem caracteres fora do ASCII visível. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.