Header Idempotency-Key

Use Idempotency-Key para tentar novamente uma solicitação sem criar uma operação duplicada. A garantia é de aceitação exatamente uma vez: dentro da janela de retenção de 3 horas, novas tentativas com a mesma chave e uma solicitação idêntica devem resultar na operação original, mesmo que você tenha perdido a resposta dela. Para a estratégia de novas tentativas, consulte Idempotência.

Header da requisição

As mutações com escopo de espaço de trabalho ou organização oferecem a reprodução de respostas descrita abaixo. Operações restritas ao usuário, operações não autenticadas sem escopo e fluxos não a utilizam. Operações com um contrato de reprodução separado definem seu comportamento na própria página de referência.

Se você omitir o header ou enviar um valor vazio, a solicitação será processada normalmente, sem deduplicação. Nos endpoints que declaram esse header, uma chave com mais de 255 caracteres retorna 422 com o código E01001 ValidationError.

As chaves têm escopo do seu espaço de trabalho, ou da sua organização em endpoints no nível da organização, e são mantidas por aproximadamente 3 horas. Após esse período, uma solicitação que reutiliza a chave é processada como uma nova solicitação.

Semântica da resposta

Uma resposta repetida é byte a byte idêntica à original (mesmo código de status, mesmo corpo), diferenciada apenas pelo header adicional:

HTTP/1.1 202 Accepted
Idempotency-Replay: true

"Identical request" abrange o método, o endpoint, os parâmetros de caminho e de consulta e o corpo bruto da solicitação. Uma diferença nesses valores, incluindo espaços em branco no JSON, gera E01005. Uploads multipart comparam nomes das partes, nomes dos arquivos e conteúdo; delimitadores e ordem das partes não afetam a reprodução. Ambos os erros 409 são retornados na resposta de erro padrão.

As respostas mantidas podem incluir rejeições 4xx. Use uma nova chave ao corrigir uma solicitação: se a rejeição tiver sido mantida, uma nova tentativa sem alterações a reproduz, e uma solicitação alterada retorna 409 E01005 IdempotencyKeyReuse.

Em caso de timeout ou 5xx, tente novamente com backoff limitado usando a mesma chave e uma solicitação idêntica dentro de três horas. A garantia de aceitação exatamente uma vez se aplica mesmo quando a resposta original foi perdida. E01033 IdempotencyUnavailable significa que esta tentativa não foi executada; não descreve o resultado de uma tentativa anterior. Mantenha a chave em cada nova tentativa.

No envio de uma mensagem, a aceitação exatamente uma vez significa um único envio aceito entre as novas tentativas correspondentes. Verifique o status da mensagem para confirmar a entrega. Após três horas, verifique o resultado da operação original antes de enviar novamente: uma chave expirada ou uma nova chave pode criar outra operação.

Comportamento do SDK

Os SDKs oficiais anexam um UUID Idempotency-Key gerado automaticamente a cada requisição de mutação. Ele é gerado uma vez por chamada lógica e reutilizado em todas as novas tentativas dessa chamada. Quando uma operação lógica abrange várias chamadas SDK, você pode fornecer sua própria chave por chamada (idempotencyKey em TypeScript, option.WithIdempotencyKey em Go, idempotency_key em Python, new RequestOptions(idempotencyKey: ...) em PHP). Para detectar uma reprodução, leia o header de resposta Idempotency-Replay pelo acessor de metadados de transporte de cada SDK: .withResponse() em TypeScript, option.WithResponseInto em Go e with_raw_response em Python.

Relacionados

• Conceitos de idempotência: estratégia de novas tentativas, design de chaves e limites de reprodução
• Respostas de erro: a resposta de erro que encapsula E01004 e E01005
• Mensagens de e-mail: o endpoint de envio, o local mais comum para usar uma chave
• Conceitos do SDK: geração automática de chaves e novas tentativas