常见错误消息

请求失败时，Bird 会返回一个结构化错误，包含机器可读的错误码、消息、文档链接和请求 ID。在程序逻辑中使用错误码进行匹配。需要支持时，选择 Feedback > Contact us 并附上请求 ID。完整的错误目录请参阅 API 错误参考。

验证错误

这类错误表示 Bird 理解了你的请求，但其中某些内容不可接受。错误会列出具体的字段或不满足的条件。

含义：发送中的每个收件人都在你的抑制列表中，没有可投递的对象，因此发送被拒绝。

可能的原因：你正在向之前硬退回、投诉或退订的地址发送邮件，这通常表明你在重复发送一份旧的或未清洗的列表。如果只有 some 收件人被抑制，发送会继续投递给其余收件人，被抑制的收件人会显示为已拒绝；只有当所有收件人都被抑制时才会出现此错误。

修复方法：检查哪些地址被抑制及原因，然后将它们从你自己的列表中移除。为什么我的邮件被拒绝了？解释了抑制拒绝是如何显示的，抑制指南介绍了如何管理抑制列表。

含义：你正在通过 Bird 的共享入门域名向非工作区已验证成员的收件人发送邮件。

可能的原因：共享域名仅允许向已验证的工作区成员和沙盒测试地址投递。

修复方法：要向真实收件人发送邮件，请验证你自己的发送域名，这将完全解除该限制。参阅从共享域名发送了解相关限制和解决途径。

含义：某个必填字段缺失、值无效，或请求中组合了不兼容的字段。

可能的原因：请求不符合该操作的 schema，或组合了不兼容的字段。错误详情会指出每个失败的字段。

修复方法：阅读错误详情并修正指出的字段。

含义：请求超出了操作、账户或发送限制。

可能的原因：突发流量超出了 API 的速率限制，或发送超出了配额，例如共享入门域名的收件人上限。

修复方法：按照错误中的补救建议操作，如有 Retry-After 值则参照其指示。对临时性限制使用退避策略进行重试。对于入门域名的每日上限，等待 UTC 日重置或验证你自己的发送域名。邮件健康标签 throttled 仅用于诊断，不会导致 API 速率限制错误。

含义：Bird 无法接受你的凭据。

可能的原因：以下三种情况之一，按大致频率排列：

错误、过期或已撤销的 API 密钥：密钥拼写错误、被截断、已过期或不再有效。密钥的 secret 仅在创建或轮换时显示一次。
密钥用于了错误的区域：API 密钥是区域性的，只能用于其所属区域的服务器。如果密钥创建于一个区域而代码调用了另一个区域，身份验证将失败。密钥前缀可以告诉你它属于哪个区域。
缺少密钥：请求中完全没有包含凭据，通常是因为在出错的环境中某个环境变量为空。

修复方法：确认密钥在你的仪表板中存在且处于活跃状态，确认你的代码正在发送该密钥，并确认你调用的区域地址与密钥匹配。如果不确定，创建一个新密钥并替换旧的。

含义：发送域名尚未完成验证，因此 Bird 无法从该域名发送。

可能的原因：DNS 记录缺失、仍在传播中或不正确，或者记录在验证后被更改。参阅域名验证检查清单了解预期时间。

修复方法：在仪表板中打开该域名的页面，找到未完成的记录。使用域名验证检查清单进行修正。在 DNS 传播期间，可使用共享入门域名进行测试发送。

使用机器可读的错误码进行匹配，因为人类可读的消息可能会变更。记录请求 ID。需要支持时，选择 Feedback > Contact us 并附上请求 ID。按照文档链接获取针对具体错误的补救方法。