Weegloo Docs - 错误

请求失败时，WEEGLOO 会同时返回格式统一的错误响应体和 HTTP 状态码。无论失败发生在哪个 API（CMA、CDA、ACMA、ACDA、Upload、Auth），响应体的结构都相同。因此只要掌握一种格式，就能以同一种方式对所有错误进行分支处理。本页将该通用格式与常见的错误码集中整理在一处。

错误响应格式

错误响应体的结构如下。下面是查询不存在的 WebHosting 时收到的响应。

{
  "requestId": "GeR3sEbvWdgvv9eW2NXeanpj2wo6qbkVXgIW7Qd3ea6",
  "sys": {
    "id": "RxcgyPTSuk4GDy6s",
    "type": "NotFound",
    "code": "WGL404001",
    "timestamp": 1781785683556
  },
  "details": {
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } }
  },
  "reason": "WebHosting(...) has been deleted or does not exist.",
  "suggestion": "Please verify WebHosting and try again."
}

各键的含义如下。

键	类型	说明
`requestId`	string	本次请求的追踪标识符。联系支持时一并提供该值，即可快速定位到对应的请求。
`sys.type`	string	错误分类。表示 `Unauthorized`、`Forbidden`、`NotFound`、`Unprocessable`、`Conflict`、`TooManyRequest` 等大类。
`sys.code`	string	具体错误码（例如 `WGL409005`）。按错误码进行分支处理时使用该值。
`sys.timestamp`	integer	错误发生时刻（epoch millis）。
`reason`	string	供人阅读的失败原因。
`suggestion`	string	有助于解决问题的提示。
`details`	object（可选）	附加信息。包含指向相关资源的 `Refer`、校验错误项列表（`errors`）等。根据错误类型的不同，该字段可能不存在。

分支处理可按需选择 sys.type（大类）或 sys.code（具体错误码）作为单位。即便 sys.type 相同，sys.code 不同则原因也不同，因此如需精确处理，请以 sys.code 为准。

校验失败时，不符合规则的项会包含在 details.errors 中。下面是在请求体中放入了 schema 中不存在的属性而导致校验失败的响应。

{
  "requestId": "yJ8KpQ2mWtnLrZ4Xv7BcEadfh3sNuMvKbGT5Pq9wRsx",
  "sys": {
    "id": "Lm2Nq9Tr8KdW4xZc",
    "type": "BadRequest",
    "code": "WGL400006",
    "timestamp": 1781776000000
  },
  "details": {
    "errors": [
      { "path": "", "message": "property 'X' is not defined in the schema", "property": "X" }
    ]
  },
  "reason": "Some values do not satisfy validation rules.",
  "suggestion": "Please check the request body and try again."
}

details.errors 中的每一项都包含不符合规则的位置（path）、说明（message）和相关属性名（property）。若存在多项，则每个不符合规则的值各对应一项。

常见错误码

下面是经常遇到的错误码。

错误码	分类	含义	常见场景
`WEB401001`	`Unauthorized`	令牌无效	`Authorization` Bearer 令牌已过期或不正确。
`WGL403001`	`Forbidden`	没有权限	调用方的角色不允许执行该操作。
`WGL404001`	`NotFound`	资源不存在或已删除	使用了错误的 `sys.id` 进行查询，或调用了尚未配置的功能（例如未关联自定义域名）。
`WGL400006`	BadRequest	请求体的值不符合校验规则	使用了错误的字段键或类型发送请求体。不符合规则的项会包含在 `details.errors` 中。
`WGL409005`	`Conflict`	资源在此期间被修改	缺少 `X-Weegloo-Version` 头，或其值与当前版本不一致（参见约定）。
`WGL422007`	`Unprocessable`	处于发布状态，无法归档	要归档 Content 或 Media，必须先取消发布。
`WGL422009`	`Unprocessable`	处于发布状态，无法删除	要删除已发布的 Content 或 Media，必须先取消发布。
`WGL429001`	`TooManyRequest`	超出方案额度	Organization、Space 等资源的创建数量超出了当前方案的额度。升级方案即可提高额度。

以上是经常遇到的一部分错误码。除此之外，根据操作和资源的不同，可能还有更多错误码。无论收到哪种错误码，都可以通过 sys.type 把握大类，并通过 reason、suggestion 确认具体原因和解决方向。

约定：用于避免 WGL409005 的 X-Weegloo-Version 并发约束。
系统属性 (sys)：发布状态（status），以及 WGL422007、WGL422009 所指向的生命周期。

错误响应格式

常见错误码

相关文档