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

# Requisições idempotentes

> Repita requisições com segurança usando o header Idempotency-Key.

A API suporta idempotência para repetir requisições com segurança sem executar
a mesma operação duas vezes — por exemplo, quando uma resposta se perde na rede.
Envie um header `Idempotency-Key` em qualquer requisição que muda estado
(`POST` e `DELETE`, em todos os recursos da API) e a Chargefy garante que a
operação roda uma única vez.

O header é **sempre opcional**: sem ele, a requisição é processada normalmente,
sem nenhuma mudança de comportamento. A chave é enviada só pelo header — não
existe parâmetro de corpo para idempotência.

<CodeGroup>
  ```bash cURL theme={}
  curl https://api.chargefy.io/v1/subscriptions \
    -H "Authorization: Bearer sk_live_..." \
    -H "Idempotency-Key: a1b2c3d4-migration-2026-07-01" \
    -H "Content-Type: application/json" \
    -d '{ "customer": "cus_123", "items": [{ "price": "price_123" }] }'
  ```
</CodeGroup>

## Como funciona

* Na **primeira** requisição com uma chave, a operação roda normalmente e a
  resposta é guardada.
* Uma **repetição** com a mesma chave **e o mesmo corpo** não executa de novo:
  devolve a resposta guardada, com o header `Idempotent-Replayed: true`.
* A chave é única por organização e por ambiente (`livemode`). A mesma chave em
  test mode e em produção são chaves distintas.
* Chaves expiram após **24 horas**. Depois disso a mesma chave pode ser reusada.
* Só vale para `POST` e `DELETE`. `GET` já é idempotente e ignora o header.

## Gerando a chave

Use um valor único por operação lógica — um UUID v4 é a escolha mais comum. Em
uma migração de assinaturas, uma boa chave é o id da assinatura no sistema de
origem, para que reimportar a mesma assinatura nunca a duplique.

## Regras e erros

<ResponseField name="Idempotency-Key" type="string">
  Até 255 caracteres. Definido por você, único por operação.
</ResponseField>

| Situação                                                | Resultado                                                                             |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Mesma chave, mesmo corpo, operação já concluída         | `200` com a resposta original + `Idempotent-Replayed: true`.                          |
| Mesma chave, **corpo diferente**                        | `400` `idempotency_key_reused`. Uma chave só pode ser usada com os mesmos parâmetros. |
| Mesma chave, requisição anterior **ainda em andamento** | `409` `idempotency_key_in_progress`. Tente novamente em instantes.                    |
| Chave com mais de 255 caracteres                        | `400` `idempotency_key_invalid`.                                                      |

<Warning>
  Respostas de erro do servidor (`5xx`) e respostas transitórias (`409`, `425`,
  `429`) **não** são guardadas. Uma chave usada em uma requisição que falhou com
  um desses status pode ser repetida normalmente.
</Warning>

## Boas práticas

* Reenvie a **mesma** chave ao fazer retry de uma requisição que pode ter
  chegado ao servidor.
* Gere uma chave **nova** para cada operação distinta.
* Combine idempotência com retry por backoff em `429` e `5xx`.