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	意外的錯誤，沒有進一步的分類。	驗證請求格式；如果問題仍然存在，請聯絡支援。