跳到主要内容

REST API 请求错误说明

更新时间 2024/11/07 12:43:21

当您与画布 REST API 交互时，可能会遇到来自服务器端的错误反馈。本章节提供了可能返回的错误状态码及其详细描述。当 API 返回错误响应时，包含的信息将帮助您诊断问题并采取相应的修正措施。

错误响应结构体​

如果一个API请求失败，您会收到一个包含错误详情的 JSON 响应体。该响应体中的字段描述了错误的类型、原因和其他相关信息，响应体格式如下：

{
  "status": "HTTP 状态码",
  "type": "error",
  "code": "错误类型",
  "message": "错误描述"
}

字段解释如下：

  • status：标准的 HTTP 状态码，反映了请求的结果，注：只有 status 为 200 时，才表示请求成功。
  • type：错误类型，对于请求错误，这个值始终是 "error"。
  • code：提供了错误类型信息，通常情况下该值是一个较为广泛的错误描述，仅会反馈在某一方面发生了错误，例如 Not Authorized。
  • message：提供了较为细节的错误信息，更方便对定位问题起到帮助。

常见服务端错误状态码​

以下列表包含了一些场景的 HTTP 状态码及通用含义：

  • 400 Bad Request: 请求 body 数据错误或格式错误。
  • 401 Unauthorized: 请求未经授权。通常是由于 Access Token 的缺失或者无效。
  • 403 Forbidden: 服务器拒绝执行请求。
  • 404 Not Found: 找不到请求的路径。通常是由于您的接口路径存在错误，或您请求了已经停止服务的路径。
  • 429 Too Many Requests: 请求因限流政策被英飞服务端拒绝。
  • 500 Internal Error: 服务器受理请求时出错。与 400 状态码类似，表英飞服务端无法受理请求，区别为该状态码下的错误信息提示通常不具备指导意义。
  • 503 Service Unavailable 或 504 Gateway Timeout: 英飞画布服务暂时无法访问。

如何处理错误响应​

  • 检查请求：确保您的请求格式正确，并符合API文档所说明的规范。
  • 重试策略：对于 429 Too Many Requests, 503 Service Unavailable 或 504 Gateway Timeout 等暂时性错误，您可以采取适当的延时重试策略。
  • 联系支持：如果错误持续出现，请联系我们的技术支持团队获得帮助。

请注意：具体的 API 调用时可能会返回其他错误码。更多详细的API特定错误信息，请参阅API参考文档。