Skip to main content

​
Por que isso existe

Se a rede cair depois que a Cakto processou sua cobrança mas antes de você receber a resposta, você fica sem saber se a cobrança foi criada. Repetir a requisição às cegas pode gerar uma cobrança duplicada. A chave de idempotência resolve isso: você identifica a operação, e a Cakto garante que ela seja executada uma única vez.

​
Onde se aplica

Hoje a idempotência é exigida em Criar Cobrança (POST /public_api/payments/). Nos demais endpoints o header é ignorado.

​
Como usar

Envie o header X-Idempotency-Key com um valor único por cobrança:
Gere a chave antes da primeira tentativa e reutilize exatamente a mesma em todas as retentativas daquela cobrança. Se você gerar uma chave nova a cada tentativa, perde a proteção.

​
Comportamento

1

Primeira requisição

A chave é registrada e a cobrança é processada normalmente. A resposta fica guardada por 24 horas.
2

Repetição com o mesmo payload

A Cakto devolve a resposta original — mesmo status e mesmo corpo. Nenhuma cobrança nova é criada.
3

Repetição enquanto a primeira ainda processa

Retorna 409. Aguarde a conclusão e consulte o resultado antes de tentar de novo.
4

Mesma chave com payload diferente

Retorna 409. A chave já pertence a outra cobrança — use uma nova para uma cobrança nova.

​
Respostas de erro

A comparação de payload é feita sobre o corpo inteiro da requisição. Qualquer diferença — inclusive um campo opcional a mais — caracteriza payload diferente e resulta em 409.

​
Falhas de servidor

Respostas com status 5xx não são armazenadas. A chave é liberada, então uma retentativa com a mesma chave é processada normalmente — é exatamente o comportamento que você quer ao tentar de novo após um erro transitório.

​
Próximos passos

Limites de requisição

Quantas requisições você pode enviar por minuto

Erros

Formato das respostas de erro da API