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

# Idempotência

> Como repetir uma escrita sem gravar o recurso duas vezes.

A rede pode cair depois que a API grava um recurso e antes que a resposta chegue ao seu sistema. Nesse caso, o seu sistema não sabe se a escrita aconteceu. Com o cabeçalho `Idempotency-Key`, o seu sistema repete a chamada, e a API grava o recurso uma vez só.

O cabeçalho é opcional e vale para todo `POST` da API. Envie o cabeçalho em todo `POST`.

## Como usar

1. Crie um valor único para cada escrita. Um UUID serve.
2. Guarde o valor junto da escrita no seu sistema.
3. Envie o valor no cabeçalho `Idempotency-Key` da chamada `POST`.
4. Se a resposta não chegar, repita a chamada com o mesmo valor e o mesmo conteúdo.

```bash theme={null}
curl https://app.useqx.com/api/v1/contacts \
  -H "Authorization: Bearer qx_sua_chave" \
  -H "Idempotency-Key: 5f0c7e8a-3a1b-4d2e-9c61-2b7f4e0d9a13" \
  -H "Content-Type: application/json" \
  -d @contato.json
```

## O que a API faz com o valor

A API compara cada chamada com a primeira chamada do mesmo valor. A comparação usa o método, o caminho, os parâmetros e o nome e o conteúdo de cada arquivo. A ordem dos campos no corpo não muda a comparação.

| Situação                                             | Resposta                                                                                             |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| O valor é novo.                                      | A API roda a chamada e guarda a resposta.                                                            |
| O valor já atendeu uma chamada com o mesmo conteúdo. | A API devolve a resposta guardada, com o mesmo status e o mesmo corpo. A API não grava nada de novo. |
| O valor já atendeu uma chamada com outro conteúdo.   | `422` com o código `idempotency_key_reused`.                                                         |
| Outra chamada com o mesmo valor ainda está em curso. | `409` com o código `idempotency_key_in_use`.                                                         |

## O que fazer com cada erro

| Status | `code`                   | O que fazer                                                                                           |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| 409    | `idempotency_key_in_use` | Espere alguns segundos. Depois, repita a chamada com o mesmo valor.                                   |
| 422    | `idempotency_key_reused` | O seu sistema usou o mesmo valor em duas escritas diferentes. Crie um valor novo para a escrita nova. |

## As respostas que a API guarda

A API guarda a resposta de sucesso (`2xx`) e os erros `409` e `422` do recurso. A repetição devolve essa resposta como ela veio na primeira vez. Para corrigir uma chamada que recebeu `409` ou `422`, use um valor novo.

A API não guarda as outras respostas, como `400`, `401`, `402`, `403`, `404`, `413`, `429` e `5xx`. Ela também não guarda os erros `idempotency_key_in_use` e `idempotency_key_reused`. A repetição de uma chamada sem resposta guardada roda de novo.

## As regras

* O valor tem de 1 a 255 caracteres. Um valor maior recebe `400` com o código `invalid_parameter`.
* Cada chave de API tem os próprios valores. Duas chaves de API podem usar o mesmo valor sem conflito.
* A repetição que recebe a resposta guardada não gasta uma escrita paga. Ela conta no limite de chamadas por minuto.
* A API guarda a resposta por 24 horas. Depois desse prazo, a API pode apagar a resposta. A chamada com o mesmo valor roda então como nova.