O que é Idempotência?

Idempotência em uma API refere-se à capacidade de executar múltiplas requisições idênticas em um curto período de tempo com a garantia de que apenas uma única requisição será processada com sucesso. Isso é especialmente útil para evitar efeitos colaterais indesejados quando uma mesma requisição é enviada mais de uma vez devido a problemas de rede ou outras falhas.

Por exemplo, imagine que um ecommerce realiza uma requisição para criar uma fatura, mas, devido a uma falha de rede, a mesma requisição é enviada duas vezes com os mesmos dados. Com o uso de uma chave de idempotência, apenas uma das requisições será processada, evitando a duplicação de pedidos.

Como usar uma chave de idempotência?

A chave de idempotência é gerada pelo próprio lojista e deve ser incluída no header da requisição, utilizando o parâmetro Idempotency-Key.

Validade da chave: 24 horas a partir do primeiro uso.

As APIs que aceitam esse recurso são:

• Criar fatura
• Criar assinatura
• Transferência para Terceiros
• Criar Pedido de Pagamento
• Criar cliente
• Cobrança direta
• Transferir Valor entre contas iugu

Se várias requisições forem enviadas com a mesma chave de idempotência no mesmo instante, apenas uma será processada com sucesso. Para as demais, será retornado o erro 409 (Conflito).

🚧 409 com resource_id: "processing"

Em alguns casos o campo resource_id virá com o valor processing. Isso é
intencional: a chave é gravada como processing antes de a operação começar
a ser executada. Ou seja, o 409 com resource_id: "processing" indica que a
requisição original ainda está em andamento — não é um erro na integração.

O tratamento correto é considerar a operação como já submetida e não reenviar
a requisição. Consulte o recurso posteriormente para obter o id definitivo.

Recipe 🧪

Veja, na prática, como montar uma requisição com Chave de Idempotência: