Request IDs

Identifique cada requisição para que um problema possa ser rastreado de ponta a ponta.

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.

curl -i https://api.ya.onl/v1/orders -H "X-API-Key: yv_live_v1_sua_api_key"

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: 9f2c1a7b4e8d4c3fa1b6e5d0c7a92341

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.

curl https://api.ya.onl/v1/orders \
  -H "X-API-Key: yv_live_v1_sua_api_key" \
  -H "X-Request-ID: 550e8400-e29b-41d4-a716-446655440000"

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:

	Request ID	Chave de idempotência
Header ou campo	`X-Request-ID`	depende do endpoint (por exemplo `event_id` em Mensagens de Template)
Muda entre tentativas	Sim, um por tentativa	Não, deve se repetir
Para que serve	Rastrear o que aconteceu	Impedir que a operação aconteça duas vezes
Quem escolhe	Você ou nós	Sempre você, a partir do seu domínio

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.