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	無法進一步分類的非預期錯誤。	驗證要求格式；如果問題持續，請聯繫支援。