Um envio aceito pode falhar depois, durante a entrega. Manter os headers da resposta permite que o suporte investigue a chamada original junto com os eventos subsequentes da mensagem.
Onde encontro o request ID?
Leia o header de resposta X-Request-Id em chamadas bem-sucedidas e com falha. Bird também inclui request_id dentro do objeto de nível superior error em falhas.
Salve o header quando seu cliente receber a resposta. Inclua-o nos logs de envios bem-sucedidos, pois um resultado inesperado de entrega pode chegar depois.
O que devo enviar ao suporte?
Envie o request ID da tentativa afetada, o horário, a operação e o resultado inesperado. Inclua o status HTTP e, se houver erro, code e name.
Uma nova tentativa tem seu próprio request ID. Se a primeira tentativa falhou e a segunda foi bem-sucedida, inclua o ID da primeira tentativa ao perguntar sobre a falha.
Para perguntas sobre entrega, inclua também o message ID. Uma solicitação de envio em lote de e-mail pode enfileirar até 100 mensagens sob um único request ID.
O que meu cliente deve registrar?
Registre o header da resposta, o status HTTP, o horário da solicitação e a operação de cada tentativa. Para erros, registre também code, name e request_id da resposta de erro.
Esses campos respondem a perguntas diferentes. O código identifica a falha documentada. O nome torna os logs legíveis. O request ID permite que o suporte rastreie a tentativa.
Mantenha o message ID retornado junto com o registro de envio da sua aplicação. Evite registrar credenciais ou corpos de mensagem apenas para reter esses identificadores.
Como conecto eventos aos meus próprios registros?
Anexe o identificador da sua aplicação usando os campos que o endpoint de envio aceita. Para envios de e-mail, metadata e tags são ecoados nos eventos de webhook.
Por exemplo, um identificador de pedido pode conectar um evento de entrega ao pedido que originou o e-mail. Mantenha o request ID separadamente para investigar a chamada API.
Qual identificador devo usar?
Use o request ID para uma tentativa API e o message ID para o histórico de entrega.
| Identificador | Use para |
|---|---|
X-Request-Id | Perguntar ao suporte sobre uma tentativa API. |
| Message ID | Acompanhar uma mensagem pelos seus eventos de entrega. |
Idempotency-Key | Tentar novamente a mesma escrita sem criar outra operação deliberadamente. |
webhook-id | Deduplicar entregas repetidas do mesmo evento. |
Seu identificador em metadata ou tags | Relacionar eventos compatíveis aos registros da sua aplicação. |
Mantenha uma chave de idempotência estável entre novas tentativas de uma mesma escrita. O request ID muda a cada tentativa. Um evento de webhook mantém seu identificador entre novas tentativas de entrega.
O guia de erros mostra onde o request ID aparece nas respostas de erro.
Em resumo
Registre o header da resposta.
X-Request-Ididentifica a tentativa, tendo ela sido bem-sucedida ou não. Erros também incluemrequest_idna resposta de erro.Mantenha cada nova tentativa separada.
Uma nova tentativa recebe um novo request ID, mesmo quando usa a mesma chave de idempotência.
Inclua o message ID para perguntas sobre entrega.
Uma única chamada API pode enfileirar várias mensagens, então o request ID sozinho pode não identificar o destinatário afetado.
Use identificadores da aplicação para relacionar registros.
Em envios de e-mail, metadata e tags levam seus identificadores para os eventos de webhook.