> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误处理

> 了解 YCloud 错误响应并安全地重试请求。

## 简介

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

## 响应

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`。 |

有关账户和发送方配额，请参阅[速率限制](/zh/api-reference/guides/api-fundamentals/rate-limits)。
在请求到达 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。

<Tip>
  联系 [YCloud 支持](mailto:service@ycloud.com) 时，请提供 `requestId`、端点、HTTP 状态和失败时间。请先移除 API 密钥和个人数据。
</Tip>

## 实现检查清单

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.