Rastreamento de requisições

O cabeçalho X-Request-Id, os demais cabeçalhos úteis das respostas e como registrar e relatar uma chamada ao suporte.

Quando algo dá errado em uma integração, a pergunta do suporte é sempre a mesma: qual foi a requisição? A API devolve em toda resposta um identificador que liga a sua chamada ao registro do servidor. Guardá-lo custa uma linha de código e encurta a investigação de horas para minutos.

O X-Request-Id

Headers

X-Request-IDstring

Opcional, na requisição. Um identificador seu (um UUID, por exemplo). Se vier, é devolvido igual na resposta e aparece nos registros do servidor. Se não vier, o servidor cria um.

Exemplo de resposta:

http

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: 3b0432f6-3113-42ea-b768-47571d234f00

{"error":"product not found"}

Recomendação: envie o seu próprio

Gerar o identificador no seu lado tem uma vantagem: você já o tem antes da resposta. Se a conexão cai ou dá tempo esgotado, você ainda sabe qual identificador procurar. Use um UUID novo por chamada, e o mesmo valor ao repetir a mesma chamada, se quiser que as tentativas sejam rastreadas juntas.

bash

curl -i "$BASE_URL/api/v1/admin/orders?per_page=1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Request-ID: $(uuidgen)"

Outros cabeçalhos de resposta úteis

Cabeçalho	Quando aparece	Para que serve
`X-Request-Id`	Sempre	Identifica a requisição.
`Retry-After`	Resposta 429	Segundos de espera antes de tentar de novo (Limites de requisições).
`Allow`	Resposta 405	Métodos aceitos na rota.
`Cache-Control`	Rotas autenticadas e de login	`no-store`: não guarde a resposta em cache. A rota de saúde permite cache de 10 segundos.
`Access-Control-*`	Chamadas com `Origin`	Regras de CORS (CORS e versões).

Não existem cabeçalhos de saldo de limite (X-RateLimit-*), de paginação (X-Total-Count, Link) nem de versão. A paginação vai no corpo (Paginação, filtros e ordenação).

Verificar se a API está no ar

A rota de saúde GET /api/v1/health não exige token nem loja, e responde com o status e um carimbo de tempo. Use-a em monitoramento e balanceadores. Detalhes em Plataforma e integrações.

O que enviar ao suporte

Para abrir um chamado sobre uma chamada específica, reúna:

O X-Request-Id da resposta (ou o que você enviou).
O endereço da loja e o horário aproximado, com fuso (as datas da plataforma são UTC).
O método e o caminho (POST /api/v1/admin/products), sem o token.
O status e o corpo da resposta.
O corpo da requisição, com dados sensíveis removidos.

Nunca envie senhas, refresh_token, tokens de app ou chaves de API em chamados ou registros.

Erros comuns

Registrar só o corpo do erro. A mensagem sozinha não localiza a chamada; guarde também o X-Request-Id.
Reaproveitar o mesmo X-Request-ID em chamadas diferentes. Ele perde o valor de identificar uma chamada. Use um por chamada.
Registrar o cabeçalho Authorization. Mascare o token em logs.
Usar o X-Request-Id como chave de idempotência. Não é: veja Idempotência.

Veja também

Erros

Os formatos de erro.

Plataforma e integrações

Saúde e localização de loja.

Limites de requisições

O 429 e o Retry-After.