Skip to main content
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. 
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" }] }'

​
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

​
Idempotency-Key
string
Até 255 caracteres. Definido por você, único por operação.
SituaçãoResultado
Mesma chave, mesmo corpo, operação já concluída200 com a resposta original + Idempotent-Replayed: true.
Mesma chave, corpo diferente400 idempotency_key_reused. Uma chave só pode ser usada com os mesmos parâmetros.
Mesma chave, requisição anterior ainda em andamento409 idempotency_key_in_progress. Tente novamente em instantes.
Chave com mais de 255 caracteres400 idempotency_key_invalid.
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.

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