Idempotência

Use idempotência quando uma interrupção, um timeout ou a perda da resposta deixar dúvida sobre o processamento de uma requisição. A chave identifica uma mesma intenção durante as tentativas e evita que um retry aceito repita seu efeito.

O header é opcional. A página de cada endpoint informa se ele aceita Idempotency-Key.

Quando usar

Envie uma chave nas requisições de criação e nas alterações em que repetir o efeito causaria duplicidade ou outra mudança indesejada. A chave não substitui o identificador do recurso, a referência do seu sistema nem a consulta do resultado.

O CLI e o console desta documentação não repetem escritas automaticamente. Seu sistema decide quando fazer o retry e deve conservar a mesma chave enquanto trata a mesma intenção.

Enviar a chave

Gere uma chave única no seu sistema e envie-a no header:

Idempotency-Key: de305d54-75b4-431b-adb2-eb6b9e546014

UUID é aceito. O valor deve ter de 1 a 255 caracteres ASCII visíveis, sem espaços nem caracteres de controle. Não inclua credenciais, documentos ou outros dados pessoais na chave.

Guarde a chave junto do pedido ou ação correspondente. O console mostra o campo em Cabeçalhos quando o endpoint aceita idempotência. O valor fica somente na memória da aba, associado à operação e à conta. O console não cria nem troca a chave entre tentativas.

Repetir a requisição

Se a resposta for perdida, repita o mesmo método, caminho, corpo e Idempotency-Key. Uma repetição compatível devolve o resultado preservado em vez de executar novamente a requisição.

Validações recusadas antes da execução não ficam armazenadas. Respostas 4xx também não são preservadas. Corrija a requisição antes de tentar novamente e mantenha a mesma chave somente quando a intenção continuar a mesma.

Se o armazenamento de idempotência estiver indisponível, uma requisição com o header recebe 503 antes de executar a ação. Essa resposta não é preservada e pode ser repetida com a mesma chave. Sem o header, a requisição segue o fluxo normal do endpoint.

Reutilizar a chave com outro método, caminho ou conteúdo recebe 422. Use a chave somente com a requisição que representa a intenção original.

Interpretar o resultado

Quando a resposta vier de uma repetição preservada, a API envia:

Idempotency-Replayed: true

O status e o corpo permanecem iguais ao resultado armazenado. Uma resposta 202 ainda representa processamento pendente. Guarde o identificador retornado e acompanhe o mesmo recurso; o replay não transforma a pendência em conclusão.

Respostas de sucesso e falhas 5xx ocorridas depois da admissão ficam preservadas. Por isso, repetir uma chave que recebeu 500 pode devolver o mesmo erro. Consulte o recurso e reconcilie o efeito antes de criar outra chave.

Um 409 IDEMPOTENCY_RESULT_UNKNOWN informa que o endpoint pode ter concluído, mas a resposta não pôde ser preservada. Consulte o recurso antes de repetir. Se a resposta trouxer Location, comece por esse endereço. Depois da reconciliação, um retry da mesma intenção mantém a mesma chave; nunca troque a chave para contornar esse estado.

Retenção e reconciliação

O resultado fica disponível por 24 horas. Depois desse prazo, a mesma chave pode iniciar outro processamento. Não use a expiração como forma de resolver uma operação financeira incerta.

Antes de trocar a chave, consulte o recurso pelo identificador, use a referência do seu sistema quando houver filtro disponível e processe os webhooks recebidos. Só envie uma nova intenção depois de confirmar o estado atual.