一个已被接受的发送请求可能在后续投递过程中失败。保留其响应请求头可以让支持团队将原始调用与消息的后续事件一起调查。
在哪里找到请求 ID？
在成功和失败的调用中读取 X-Request-Id 响应请求头。Bird 在失败时还会在顶层 error 对象中包含 request_id。
在客户端收到响应时保存该请求头。对于成功的发送也应记录，因为意外的投递结果可能稍后才出现。
应该向支持团队发送什么？
发送受影响尝试的请求 ID、时间、操作及异常结果。附上 HTTP 状态以及任何错误的 code 和 name。
重试有自己的请求 ID。如果第一次尝试失败而第二次成功，在询问失败原因时应提供第一次尝试的 ID。
对于投递问题，还需附上消息 ID。一个邮件批量请求可以在一个请求 ID 下将最多 100 条消息加入队列。
客户端应该记录什么？
为每次尝试记录响应请求头、HTTP 状态、请求时间和操作。对于错误，还需记录错误响应中的 code、name 和 request_id。
这些字段各自回答不同的问题。错误码标识已记录的故障类型。名称使日志更易读。请求 ID 让支持团队追踪该次尝试。
将返回的消息 ID 与你应用中的发送记录一起保存。不要为了保留这些标识符而记录凭据或消息正文。
如何将事件关联到我自己的记录？
使用发送端点支持的字段附加你应用的标识符。对于邮件发送，metadata 和 tags 会在 webhook 事件中回传。
例如，订单标识符可以将投递事件关联到触发该邮件的订单。请求 ID 应单独保存，用于调查 API 调用。
应该使用哪个标识符？
使用请求 ID 标识一次 API 尝试，使用消息 ID 查看投递历史。
| 标识符 | 用途 |
|---|---|
X-Request-Id | 向支持团队询问某次 API 尝试的情况。 |
| 消息 ID | 跟踪一条消息的投递事件。 |
Idempotency-Key | 重试同一写操作而不会重复创建另一个操作。 |
webhook-id | 对同一事件的重复投递进行去重。 |
你在 metadata 或 tags 中的标识符 | 将支持的事件关联到你应用的记录。 |
在同一写操作的多次重试中保持幂等键不变。请求 ID 随每次尝试而变化。webhook 事件在投递重试中保持其标识符不变。
错误指南展示了请求 ID 在错误响应中出现的位置。
简而言之
记录响应请求头。
X-Request-Id标识该次尝试，无论成功还是失败。错误响应还会在其错误响应中包含request_id。将每次重试分开记录。
重试会获得一个新的请求 ID，即使使用相同的幂等键。
投递问题需附上消息 ID。
一次 API 调用可以将多条消息加入队列，因此仅凭请求 ID 可能无法定位受影响的收件人。
使用应用标识符关联记录。
在邮件发送中，metadata 和 tags 会将你的标识符传递到 webhook 事件中。