错误处理

简介

YCloud 使用 HTTP 状态码和结构化错误响应体，以便您的应用程序决定是修正、拒绝还是重试请求。

响应

失败的请求会返回一个 error 对象。

{
  "error": {
    "status": 404,
    "code": "NOT_FOUND",
    "message": "The requested resource does not exist.",
    "requestId": "req_1KjtKI80IKoaJNa6n6p"
  }
}

错误字段

字段	说明
`status`	必需。API 返回的 HTTP 状态码。
`code`	必需。机器可读的 YCloud 错误代码。
`message`	面向开发者的说明。请勿直接展示给最终用户。
`target`	与错误关联的请求字段或资源（若有）。
`docUrl`	了解更多信息的链接（若有）。
`requestId`	请求标识符，也会在 `YCloud-Request-ID` 标头中返回，用于与 YCloud 支持团队追踪请求。
`whatsappApiError`	原始 WhatsApp 错误详情，适用于直接 WhatsApp API 请求到达 Meta 但失败的情况。

错误代码

使用 error.code 区分具有相同 HTTP 状态码的失败请求。此目录列出了 YCloud API 错误代码；具体端点可能会说明其他错误。

代码	HTTP 状态码	含义及操作
`ACCOUNT_LIMITED`	`403`	账户限制阻止了该操作。例如，测试账户只能发送到预先验证的号码。请检查适用的账户限制。
`ACCOUNT_RATE_LIMITED`	`429`	账户配额已耗尽。请暂停共享该配额的请求并遵循 `Retry-After`。
`ACCOUNT_UNAVAILABLE`	`403`	账户不可用。请联系 YCloud 支持团队。
`ALREADY_EXISTS`	`409`	资源已存在。在创建另一个资源之前，请检查现有资源和请求参数。
`BAD_REQUEST`	`400`	请求参数无效。请根据错误详情修正请求。
`BALANCE_INSUFFICIENT`	`403`	账户余额不足。请在重试前充值。
`CONTENT_PROHIBITED`	`403`	内容违反服务条款。请修正或删除违规内容。
`CONTENT_TOO_LARGE`	`413`	请求内容过大。请减小其大小。
`EMAIL_DOMAIN_UNVERIFIED`	`403`	邮箱域名未验证。请完成验证并等待生效。
`FORBIDDEN`	`403`	您无法访问该资源。请检查其归属关系和您的账户权限。
`INTERNAL_SERVER_ERROR`	`500`	YCloud 遇到服务器错误。对于临时性故障，请根据操作的重试规则使用有界退避进行重试。
`MESSAGING_REGION_UNSUPPORTED`	`400`	所请求的地区不支持发送消息。请检查目标地区。
`NOT_FOUND`	`404`	资源不存在。请检查其 ID 和端点路径。
`PARAM_INVALID`	`400`	参数值无效。请修正错误详情中指出的字段。
`PARAM_INVALID_LENGTH`	`400`	参数超出允许的长度。请检查该字段的限制。
`PARAM_MISSING`	`400`	缺少必需参数。请在请求中包含该参数。
`PARAM_NOT_MATCH`	`400`	两个或多个参数不一致。请检查它们之间要求的关联关系。
`RECIPIENT_IN_BLOCK_LIST`	`403`	收件人已被拦截。发送前请检查账户的黑名单。
`RECIPIENT_UNSUBSCRIBED`	`403`	收件人已退订。请遵循退订意愿并检查您的退订记录。
`SENDER_ID_UNAVAILABLE`	`403`	SMS Sender ID 未注册或仍在审核中。请检查其注册状态。
`SENDER_RATE_LIMITED`	`429`	发送方配额已耗尽。请放缓使用该发送方的请求并遵循 `Retry-After`。
`SERVICE_UNAVAILABLE`	`503`	服务暂时不可用或过载。在确保操作安全的前提下稍后重试。
`SMS_SIGNATURE_UNAVAILABLE`	`403`	中国大陆短信签名不可用。请检查 SMS 签名。
`TOO_MANY_REQUESTS`	`429`	请求过于频繁。请遵循 `Retry-After`，并通过退避和抖动减少请求流量。
`UNAUTHORIZED`	`401`	身份验证失败。请检查 `X-API-Key` 中的 API 密钥。
`WHATSAPP_PHONE_NUMBER_UNAVAILABLE`	`403`	WhatsApp 电话号码不可用。请检查发送号码。
`WHATSAPP_TEMPLATE_UNAVAILABLE`	`403`	WhatsApp 模板缺失或未获批准。请检查其名称和状态。
`WHATSAPP_WABA_UNAVAILABLE`	`403`	WhatsApp 商业账户不可用。请检查请求所使用的 WABA ID。
`WHATSAPP_TEMPLATE_UNEDITABLE`	`403`	模板在当前状态下无法编辑。编辑要求状态为 `APPROVED`、`REJECTED` 或 `PAUSED`。

有关账户和发送方配额，请参阅速率限制。在请求到达 WhatsApp 后，Meta 错误也可能会出现在 error.whatsappApiError 中。请将这些详细信息与 YCloud 错误代码一并保留。

如何处理响应

状态	建议操作
`400`	修正请求参数或请求体。
`401`	检查 API 密钥。切勿在未修改凭据的情况下重试。
`403`	使用 `error.code` 检查账户、余额、收件人或资源限制。纠正原因后再进行重试。
`404`	检查资源 ID 和端点路径。
`429`	遵循 `Retry-After`，减少请求流量，并使用有界退避。
`5xx`	对于临时性失败，使用指数退避和抖动进行重试。

请求关联

记录端点、HTTP 方法、响应状态、YCloud requestId 以及您自己的关联 ID。请移除 API 密钥和个人数据。这能为您提供充足的排查依据，且不会泄露敏感信息。

安全重试

对于临时性失败，可以重试只读请求。对于消息发送和其他创建操作，请谨慎处理。重复发送 POST 可能会创建多余的资源或发送重复的消息。在请求架构支持时，请将 externalId 设置为您系统中的唯一值。在请求成功后，保存 YCloud 响应 ID。

联系 YCloud 支持时，请提供 requestId、端点、HTTP 状态和失败时间。请先移除 API 密钥和个人数据。

实现检查清单

依据 code 解析错误，而不是匹配 message 文本。
为每个出站请求设置超时时间。
仅重试临时性失败。
加入指数退避、抖动以及最大尝试次数限制。
在请求支持时，使用您自己的稳定标识符来防止产生重复的 POST 影响。

开始使用

指南

接口

Webhooks

简介

响应

错误字段

错误代码

如何处理响应

请求关联

安全重试

实现检查清单

​简介

​响应

​错误字段

​错误代码

​如何处理响应

​请求关联

​安全重试

​实现检查清单

简介

响应

错误字段

错误代码

如何处理响应

请求关联

安全重试

实现检查清单