Header Idempotency-Key

A API da Bird oferece deduplicação opcional de solicitações pelo cabeçalho Idempotency-Key. Esta página define o contrato HTTP; para a estratégia de novas tentativas, consulte Idempotência.

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 cabeçalho ou enviar um valor vazio, a solicitação será processada normalmente, sem deduplicação. Nos endpoints que declaram esse cabeçalho, 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.

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.

Respostas 5xx nunca são armazenadas em cache. Tente novamente com backoff usando a mesma chave e requisição. 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.

Uma operação pode surtir efeito antes de sua resposta ser retida. Se essa resposta for perdida, ou o bloqueio em andamento expirar, uma nova tentativa pode executar a operação novamente. Um timeout ou outra resposta 5xx, portanto, não prova que a operação não teve efeito.

Os SDKs oficiais anexam um UUID Idempotency-Key gerado automaticamente a cada requisição de mutação, gerado uma vez por chamada lógica e reutilizado em todas as tentativas de reenvio dessa chamada. Você pode fornecer sua própria chave por chamada (idempotencyKey em TypeScript, option.WithIdempotencyKey em Go, idempotency_key em Python) quando uma operação lógica abrange múltiplas chamadas SDK. Para detectar um replay, 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.