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.

​
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 24 horas depois de a operação concluir. Depois disso a mesma chave pode ser reusada para uma operação nova.
  • 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

​
string
Até 255 caracteres. Definido por você, único por operação.

​
Quando a requisição falha

O retry com a mesma chave é sempre seguro de enviar. O que ele encontra depende de até onde a operação tinha chegado. Erros de servidor (5xx) e respostas transitórias (409, 425, 429) não são guardados como resultado final: a chave continua utilizável e o retry executa a operação novamente.

​
Criação de assinaturas: retomada pós-falha

POST /v1/subscriptions tem uma garantia adicional. A criação grava vários objetos de uma vez — assinatura, itens, primeira fatura, desconto —, então uma falha depois dessa gravação não devolve a chave ao início: o retry com a mesma chave retoma a mesma operação, termina o que faltava e devolve a mesma assinatura — nunca cria uma segunda. Nesse endpoint, um 5xx não significa que nada foi criado; significa que a operação não terminou, e repetir com a mesma chave é como você descobre em que pé ela ficou.
Sem Idempotency-Key essa garantia não existe entre requisições. Se a resposta se perder no caminho, não há como saber que a nova requisição é a mesma operação — e você pode acabar com dois recursos.

​
Boas práticas

  • Reenvie a mesma chave ao fazer retry de uma requisição que pode ter chegado ao servidor. É o retry com a mesma chave que evita o recurso duplicado; um retry com chave nova é uma operação nova.
  • Gere uma chave nova para cada operação distinta.
  • Combine idempotência com retry por backoff em 429 e 5xx.