API 错误

了解并解决 Zonos GraphQL API 返回的错误。

GraphQL

Zonos API 返回两种类型的错误：HTTP 状态代码用于传输级别的失败，GraphQL 错误用于应用级别的问题。大多数错误是 GraphQL 错误，包括 extensions 字段中的分类，以帮助识别原因和适当的解决方案。

HTTP 状态代码

HTTP 错误在请求无法在传输级别处理时返回。

状态代码↕	含义↕
400	无效的参数 / 不当的请求 — 请求包含无效的输入。
401	未授权 — 未提供有效凭证。
404	未找到 — 请求的资源不存在。
409	资源冲突 — 请求与资源的当前状态冲突。
412	先决条件失败 — 处理前未满足所需条件。
422	无法处理的实体 — 请求体在结构上有效，但包含无效的值。
429	速率限制 — 短时间内请求过多。使用指数退避并重试。
500	内部服务器错误 — 发生了意外的服务器端失败。重试；如果问题持续，请联系支持。
503	服务不可用 — 服务临时离线。在短暂延迟后重试。
504	超时 — 服务器未及时收到响应。重试请求。

应用级别的错误以响应体的 errors 字段中的列表返回。每个错误包括 message、失败操作的 path 和一个带有错误类型和请求 ID 的 extensions 对象。

1{

2 "errors": [

3 {

4 "message": "Description of the error",

5 "path": [

6 "landedCostCalculate"

7 ],

8 "extensions": {

9 "errorType": "BAD_REQUEST",

10 "requestId": "req_abc123"

11 }

12 }

13 ]

14}

extensions.errorType 字段指示错误的类别和建议的操作。

分类↕	HTTP 等价↕	含义↕	操作↕
`BAD_REQUEST`	400	无效的输入或请求参数。	修复请求 — 检查必填字段、格式和值。
`NOT_FOUND`	404	引用的资源不存在。	验证 ID、代码，并确保配置了所需的默认值。
`UNAVAILABLE`	503	请求的服务或选项对此路由不可用。	尝试不同的方法、服务级别或目的地。
`PERMISSION_DENIED`	401 / 403	身份验证或授权失败。	检查凭证和帐户权限。
`FAILED_PRECONDITION`	412	未满足所需的配置或设置条件。	检查组织设置或联系支持。
`INTERNAL`	500	发生了意外的服务器端失败。	重试请求；如果问题仍然存在，请联系支持。
`UNKNOWN`	500	没有进一步分类的意外错误。	验证请求格式；如果问题仍然存在，请联系支持。