Toda criação (POST /v1/pix/charges, POST /v1/pix/transfers, POST /v1/pix/received/{id}/refunds) exige o header Idempotency-Key. Sem ele: 400 idempotency_key_required. Fora do formato (8 a 128 caracteres ASCII visíveis, sem espaço): 400 validation_error.
O evento de teste e o reenvio de eventos não usam Idempotency-Key.

​
Como funciona

A chave fica presa ao external_id do recurso. Para o mesmo external_id: Se a primeira tentativa foi recusada com 4xx, nenhum dinheiro se moveu e o external_id fica livre para um request corrigido.

​
Regra de ouro

Uma chave por intenção de pagamento. Timeout, erro de rede ou 5xx? Repita com a mesma chave. Nunca gere uma chave nova para “tentar de novo”: se o primeiro request chegou, você paga duas vezes.
Use algo derivado do seu próprio ID, ex. transfer-{id_do_saque}. Assim a chave sobrevive a um restart do seu sistema. O external_id é uma segunda trava: ele é único por conta e tipo de recurso, então um segundo PIX com o mesmo external_id e outra chave devolve 409 external_id_conflict com o id do recurso que já existe.