Skip to main content

​
Request IDs

Cada resposta da API inclui um header X-Request-ID que identifica aquela requisição específica. É o dado que transforma um “falhou ontem à tarde” em algo que conseguimos procurar.

​
Recebendo

Não é preciso fazer nada: o header vem em toda resposta, incluindo os erros 401, 403, 404, 422, 429 e 502.
Guarde esse valor nos seus logs junto com a resposta. Se precisar reportar um problema, o X-Request-ID da requisição que falhou é a primeira coisa que vamos pedir — com ele encontramos a requisição exata nos nossos registros em segundos, sem adivinhar.
A única exceção é o 500 InternalServerError. Uma exceção não tratada é respondida por uma camada que fica fora de onde o header é adicionado, então essa resposta não traz X-Request-ID — justamente o caso em que ele mais faz falta. Do nosso lado o identificador fica registrado; para reportar um 500, envie o horário exato com fuso e o endpoint, que conseguimos localizar mesmo assim.

​
Enviando o seu

Se o seu sistema já gera identificadores de requisição, envie-os e nós os adotamos: eles ficam nos nossos logs e no registro de auditoria, então o seu identificador e o nosso são o mesmo e o rastro cruza a fronteira entre os dois sistemas.
Deve ser um UUID versão 4 (com ou sem hífens). Um valor em qualquer outro formato é descartado silenciosamente e geramos um nosso no lugar: a resposta trará um X-Request-ID que não é o que você enviou, e o seu identificador não ficará registrado em lugar nenhum.
Os identificadores que geramos têm 32 caracteres hexadecimais sem hífens (9f2c1a7b4e8d4c3fa1b6e5d0c7a92341); ambas as formas são válidas.

​
Um por tentativa, não por operação

Um request ID identifica uma tentativa de requisição. Se você tentar de novo após um timeout, essa nova requisição leva um request ID novo — é isso que mantém as duas tentativas distinguíveis nos registros. Isso é exatamente o oposto de uma chave de idempotência, que deve ser a mesma em todas as tentativas para que a operação não seja executada duas vezes. Não use o mesmo valor para as duas coisas:
Usar um identificador novo por tentativa como chave de idempotência quebra a proteção contra duplicados sem gerar nenhum erro: cada tentativa parece uma operação distinta. Em um endpoint que envia mensagens, isso significa que o seu cliente recebe a mensagem duas vezes.