Chave de idempotência reutilizada

chave_idempotencia_reutilizada

A mesma Idempotency-Key já foi usada com outro corpo, ou em outra rota.

O que aconteceu

A chave já está registrada para uma requisição concluída, e o corpo que você mandou agora é diferente. Devolver a resposta antiga seria pior: você acharia que criou o documento novo.

Por que costuma acontecer

• A armadilha mais comum: derivar a chave da sua referência externa (por exemplo com:OS-4711). Isso é ótimo contra retentativa de rede e péssimo quando você quer reenviar o mesmo contrato de propósito — você recebe a resposta antiga, ou este erro.
• Um laço de retentativa reaproveitou a chave depois de alterar o payload.

Como resolver

• Para repetir uma requisição que pode ter falhado no meio: use a mesma chave. É para isso que ela existe.
• Para criar de novo de propósito (recriar um contrato após recusa, por exemplo): use um UUID v4 novo. Isso funciona porque referencia_externa não é única.

As duas intenções, explícitas

// retentativa da MESMA operação — mesma chave
const chave = com:${referenciaExterna}

// recriar o contrato de propósito — chave nova
const chave = crypto.randomUUID()

Relacionados

• requisicao_em_andamento — Requisição em andamento
• entrada_invalida — Entrada inválida

Ramifique sempre pelo campo codigo da resposta — ele é estável. Nunca pelo texto da mensagem nem por esta URL.