错误

Management API、Content Delivery API 和 Customer API 返回的错误格式完全一致。每个错误代码在所有 API 中均对应相同的 HTTP 状态码，因此您只需编写一个错误处理器即可适用于所有 API。

{
  "error": {
    "code": "SLUG_TAKEN",
    "message": "Another post already uses this slug.",
    "details": { "slug": "how-we-feed-our-starter" }
  }
}

成功的响应绝不会包含 error 字段，且 API 不会将成功响应包裹在 ok 标志中。

错误代码对应的 HTTP 状态码

每个错误代码均对应一个状态码。未来新增的代码亦遵循相同规则，因此您可以根据状态码来处理尚未遇到的错误代码。

API 参考文档中的每项操作均列出了其可能返回的错误代码及其含义。OpenAPI 文档中亦包含相同的列表，标记为 x-kanorio-errors。

验证错误

VALIDATION 错误会在 details.issues 中列出所有验证失败的字段。path 字段使用点号（.）来表示嵌套结构。

{
  "error": {
    "code": "VALIDATION",
    "message": "Input does not match the capability schema.",
    "details": {
      "issues": [
        { "path": "title", "message": "Required", "code": "invalid_type" }
      ]
    }
  }
}

Content Delivery API 的表单提交若包含无效回答，会以相同方式报告，并将问题 ID 作为 path。

重试机制

• 针对 429、502 和 503 错误，请使用退避算法（backoff）进行重试。若响应中包含 Retry-After 标头或 details.retryAfter 字段，请至少等待该秒数后再重试。
• 请勿直接重试其他 4xx 错误，应先修正请求内容。
• 若写入操作出现 409 CONFLICT，代表资源在您读取后已被他人修改。请重新读取资源、合并变更，并使用新的时间戳再次发送写入请求。
• 请使用 幂等性键值 确保创建请求可安全重试。

权限错误

403 响应会在 details 中说明缺失的权限，例如令牌缺乏的 requiredScope，或是当服务账号调用账号层级操作时显示 reason: "principal_not_allowed"。遇到此类错误时，请引导用户进行修正，而非进行重试。

请求 ID

Content Delivery API 和 Customer API 的响应均包含 X-Request-Id 标头。若需联系支持团队查询特定请求，请提供此 ID。

错误代码

下表列出了目前各 API 可能返回的所有错误代码，内容由 OpenAPI 文档自动生成。

Management API codes

Content Delivery API codes

Customer API codes