錯誤與恢復

根據穩定的錯誤代碼決定修正、等待還是重試。

處理方法

請根據 HTTP 狀態和 error.code 分支處理，不要依賴面向人的 error.message。
401 要求有效身份驗證；403 要求調整存取權限或方案；409 要求檢查衝突操作或資源版本。

存取遭拒與重試

401: 401 不一定代表權杖已過期。如果已過期，取得新權杖後最多重試讀取一次。如果取得權杖時回傳 401，請檢查金鑰並停止自動嘗試。
403: 遇到 403 時，請檢查權限、IP 限制及方案。取得新權杖不會恢復已撤銷的存取權限。

身份驗證

重試策略

對於臨時故障，使用次數受限、逐步延長等待並帶隨機抖動的重試。
有 Retry-After 時應遵守。
寫入超時時，其結果可能未知：重試同一邏輯操作時，保留原來的 Idempotency-Key 和未修改的請求。
下方目錄解釋所有已公開的錯誤代碼。

安全寫入

速率限制

422 / 409

對於價格，無效的貨幣格式或金額精確度會傳回 422 request.validation_failed。
有效的貨幣代碼若與所選價目表不一致，則傳回 409 resource.version_conflict。
重試前請檢查情境與版本。

錯誤目錄

400request.malformed無法解析請求。

處理方法: 檢查 JSON 語法、URL 編碼及請求結構。
重試策略: 修正請求後重試。

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsAPI 金鑰或存取權杖無效、過期或已撤銷。

處理方法: 檢查商店 URL 和憑據。使用有效 API 金鑰取得新權杖。
重試策略: 修正身份驗證後重試；避免反覆傳送無效權杖請求。

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.required缺少所需的 Authorization 請求標頭，或其方案不正確。

處理方法: 取得權杖時使用 ApiKey，資源操作使用 Bearer。
重試策略: 提供正確請求標頭後重試。

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverified服務無法確定可信的用戶端 IP 位址。

處理方法: 請商店維運人員檢查入口鏈路。不要自行添加轉發請求標頭。
重試策略: 恢復可信連接鏈路後重試。

JSON

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowed來源 IP 位址不在金鑰允許的位址清單中。

處理方法: 使用獲准的來源位址，或請獲授權的管理員編輯金鑰 IP 清單。
重試策略: 只有在位址獲准後才重試。

JSON

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_denied金鑰不具備此操作所需的有效權限。

處理方法: 檢查操作所需的權限及條件權限、金鑰授權和核發者的存取權限。
重試策略: 獲授權的管理員授予所需權限後再重試。

JSON

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabled此商店的 API 存取已停用。

處理方法: 請店主檢查目前方案及 API 可用性。
重試策略: 啓用 API 存取前不要重試。

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceeded變更會超出目前方案的限制。

處理方法: 檢查適用資源限制，並調整計劃的變更或方案。
重試策略: 解決限制後重試；若請求改變，請使用新的冪等鍵。

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabled目前方案不包含此操作。

處理方法: 檢查該操作註明的最低方案。
重試策略: 方案允許操作且金鑰具有所需權限後再重試。

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blocked方案限制阻止存取此資源。

處理方法: 請店主解決該資源的方案限制。
重試策略: 資源仍被阻止時，不要重複相同請求。

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_found資源不存在、已刪除，或無法通過給定識別碼存取。

處理方法: 檢查商店、資源路徑和識別碼。使用此商店回傳的識別碼。
重試策略: 修正目標或確認目標存在後才重試。

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowed端點不支援此 HTTP 方法。

處理方法: 使用文件規定的方法；Allow 回應標頭列出支援的方法。
重試策略: 不要重試不支援的方法。

JSON

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reused此冪等鍵屬於另一個請求。

處理方法: 查找原始操作。只有確實要進行新的邏輯操作時，才使用新金鑰。
重試策略: 不要使用衝突的金鑰重試已改變的請求內容。

JSON

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_exists唯一值與現有資源衝突。

處理方法: 讀取現有資源，決定使用它還是選擇其他唯一值。
重試策略: 不要重複相同的衝突建立操作。

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_use其他資源仍依賴此資源。

處理方法: 檢查依賴關係；刪除前，通過支援的操作移除或修改依賴。
重試策略: 處理依賴關係後重試。

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflict目前業務狀態阻止此變更。

處理方法: 讀取目前狀態並選擇有效的業務狀態轉換。
重試策略: 不要自動強制執行或反覆提交衝突變更。

JSON

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflict在你讀取版本後，另一次寫入改變了資源。

處理方法: 讀取最新狀態，協調變更，再提交新的 expected_version。
重試策略: 為調整後的操作使用新的冪等鍵；不要盲目覆蓋。

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_large請求超出大小限制。

處理方法: 減小請求內容，或將工作拆分為支援的獨立操作。
重試策略: 使用各自的冪等鍵重試更小且有效的操作。

JSON

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_type不支援該媒體類型或內容編碼。

處理方法: JSON 寫入使用 Content-Type: application/json，並傳送受支援的未壓縮請求本文。
重試策略: 修正媒體類型或編碼後重試。

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failed一個或多個欄位或參數未通過驗證。

處理方法: 查看 error.fields，再檢查必填欄位、是否允許 null、識別碼和允許值。
重試策略: 修正請求後重試；已改變的寫入屬於新的邏輯操作。

JSON

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullAPI 短佇列已滿；請求尚未開始執行。

處理方法: 將請求排入隊列，並遵守 Retry-After 回應標頭。
重試策略: 至少等待 Retry-After 秒，並增加隨機延遲。重試寫入時保留原始金鑰和請求內容。

JSON

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutAPI 佇列等候逾時；請求尚未開始執行。

處理方法: 將請求排入隊列，並遵守 Retry-After 回應標頭。
重試策略: 至少等待 Retry-After 秒，並增加隨機延遲。重試寫入時保留原始金鑰和請求內容。

JSON

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceeded請求速率超出適用限制。

處理方法: 將請求排入隊列，並遵守 Retry-After 回應標頭。
重試策略: 至少等待 Retry-After 秒，並增加隨機延遲。重試寫入時保留原始金鑰和請求內容。

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.error發生意外服務錯誤。

處理方法: 記錄請求識別碼；錯誤持續時聯繫維運人員。日誌中不得包含憑據。
重試策略: 使用次數受限的退避重試。寫入時保留原始冪等鍵和未修改的內容。

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_response閘道未收到有效的 API 回應。

處理方法: 保留請求識別碼。失敗回應不代表寫入未被執行。
重試策略: 使用次數受限的退避重試；重複同一邏輯寫入時，保留原始 Idempotency-Key 和請求內容。

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableAPI 暫時無法處理請求。

處理方法: 如有 Retry-After 請遵守；故障持續時保留請求識別碼。
重試策略: 使用次數受限、帶隨機抖動的退避重試；重複同一寫入時保留金鑰和請求內容。

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeout閘道等待 API 回應超時。

處理方法: 保留請求識別碼，並將寫入結果視為未知。
重試策略: 使用次數受限的退避重試；寫入時複用原始冪等鍵和未修改的內容。

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}