Sign inGet Started

错误响应

每个失败的请求都会在顶层 error 键下返回相同的 JSON 信封,并附带一个 HTTP 状态来告知你粗略的类别。本页是线上契约;关于分支策略、重试和错误码目录的设计理念,请参阅错误。
代码示例
{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request validation failed.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01krdgeqcxet5s7t44vh8rt9mg",
    "details": [
      { "param": "contact_id", "message": "this field is reserved and not yet supported" },
      { "param": "topic_id", "message": "this field is reserved and not yet supported" }
    ]
  }
}

信封字段

字段是否始终存在描述
type是用于粗略分支的大类:一个封闭枚举(auth_error、validation_error、rate_limit_error,……)。
code是与 E\d{5} 匹配的不透明、稳定标识符。唯一、不会重命名、不会重用;匹配时应以此为准。
name是人类可读的简称(ValidationError),用于提升日志可读性。始终与 code 成对出现,不可替代它。
message是人类可读的描述。不稳定;可以显示或记录到日志,切勿解析。
doc_url是指向该 code 文档页面的稳定链接。
request_id是关联 ID,也作为 X-Request-Id 响应请求头返回。在提交支持请求时请附上此值。
param否出错的字段,当错误由单个字段引起时出现。
details否以 {param, message} 对象表示的逐字段验证失败,其中 param 是类似 to[0].email 的点分路径。仅在 validation_error 响应中出现。
vendor_code否来自下游系统的原始代码(SMTP 回复码、支付拒绝码),在值得采取行动时出现。

HTTP 状态映射

每个 type 恰好映射到一个 HTTP 状态,因此状态码与信封始终一致。
状态type含义
400bad_request_error请求格式错误:无法解析的请求体或无效的请求头(例如错误的 Idempotency-Key)。
401auth_error请求携带了缺失、无效或已吊销的凭据。请参阅身份验证。
402billing_error请求需要组织尚未具备的支付方式、余额或套餐。请参阅账单与用量。
403permission_error凭据有效,但无权执行此请求。请参阅身份验证。
404not_found_error没有路由匹配此路径,或该资源在此工作区中不存在。请参阅区域。
409conflict_error请求与资源的当前状态冲突,包括幂等性冲突(E01004、E01005)。请参阅幂等性。
410gone_error资源曾经存在,但已被永久删除。
412precondition_error此请求的前置条件未满足。
413payload_too_large_error请求体超过了允许的最大大小。
421misdirected_error请求到达了一个无法为其提供服务的区域。请参阅区域。
422delivery_error消息已作为请求被接受,但无法按指定地址投递。
422validation_error请求体已成功解析,但一个或多个值无效。
425too_early_error请求到达的时间早于可处理的时间。
429rate_limit_error此工作区的某个速率限制组已耗尽。请参阅请求速率限制。
499client_closed_request_error连接在响应就绪前关闭,通常是因为调用方停止了等待。
500internal_error处理请求时我们这边出现了故障。请参阅幂等性。
501not_implemented_error该端点已在 API 中声明,但尚未实现。
503service_unavailable_error此请求所依赖的某个服务暂时不可用。

在 SDK 中处理错误

每个 SDK 都会将信封映射到其语言的原生错误模型,并在错误值上携带所有信封字段(type、code、message、doc_url、request_id,……)。
import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";

try {
  await bird.email.send({
    from: { email: "onboarding@messagebird.dev", name: "Bird" },
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Bird",
    html: "<p>My first Bird email.</p>",
  });
} catch (err) {
  if (err instanceof BirdRateLimitError) console.log(`rate limited; retry in ${err.retryAfter}s`);
  else if (err instanceof BirdValidationError) console.error(err.details);
  else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
  else throw err;
}

错误码目录

公共 Bird API 返回的所有错误码,按代码范围拆分为每个范围一页。每个范围页面列出其错误码,每个错误码有自己的页面说明原因和处理方式。任何错误响应中的 doc_url 都直接链接到该错误码的页面。
范围领域错误码数
E01xxx基础设施30 个错误码,2 个已停用
E02xxx认证与身份9 个错误码,2 个已废弃
E03xxx账单与套餐12 个错误码
E04xxx邮件发送与投递67 个代码,3 个已废弃
E05xxx域名与 DNS19 个错误码
E06xxxWebhooks7 个错误码
E07xxx钱包4 个错误码
E10xxx配额9 个错误码,2 个已停用
E11xxxIP 池与专用 IP4 个错误码,1 个已废弃
E12xxxSMS 发送与投递49 个错误码,5 个已废弃
E13xxxVerify7 个错误码,1 个已废弃
E14xxx号码5 个错误码
E15xxxWhatsApp 发送与投递49 个错误码
E16xxx信任1 个错误码
E17xxx坐席邮箱14 个错误码,2 个已废弃
E19xxx注册合规4 个错误码
E21xxx语音与 SIP 中继16 个代码,7 个已废弃
E22xxx号码查询4 个错误码
E23xxx实时1 个错误码
E24xxxCompetitive Insights6 个错误码
E25xxxSendability5 个错误码,1 个已废弃
E27xxxInbox Insights5 个错误码
E28xxxApple Messages for Business29 个错误码,2 个已废弃
E32xxx操作确认6 个错误码

相关内容