錯誤代碼 - Return Helper API

此頁面由 AI 自動翻譯。如有任何疑問或不一致之處，請以英文版本為準。

每個 API 回應都使用標準信封（correlationId + meta + payload — 見錯誤處理）。當出現錯誤時，meta.errorCode 是機器可讀的錯誤鍵。本頁列出 User 與 Public API 可能產生的全部值。

如何閱讀本頁

Wire HTTP 欄是回應實際抵達時的 HTTP 狀態碼。 meta.status 欄是回應體內部的應用層狀態。 meta.errorCode 欄是您在用戶端程式碼中進行分支判斷的值。 meta.error 欄描述每筆錯誤明細的形態。本 API 的多數錯誤路徑會回傳 HTTP 200，並把邏輯狀態放在 meta.status 中（軟錯誤約定）。少數情況下會回傳真實的 HTTP 400/401/403/409——這些情況發生在回應信封被套用之前，或代表真正的 HTTP 語意。

驗證失敗

幾乎每個寫入端點都會經過 FluentValidation。在此被攔截的任何內容——缺少必填欄位、值超出範圍、國家代碼無效、批次超出上限、以 Custom(...) 檢查表達的業務規則違反——都會歸併到同一個錯誤代碼：

Wire HTTP	`meta.status`	`meta.errorCode`	`meta.error`
`200`	`400`	`VALIDATION_FAILED`	以請求屬性名為鍵的物件 → 以逗號連接的錯誤訊息列表。對於批次端點（例如 `/api/Recall/createRecallByReturnInventoryId`），`jobEntryList` 內的項目會單獨顯示，方便您定位是哪一筆失敗。

範例回應體：

{
  "correlationId": "0HNLB2U6T1QG1:00000001",
  "meta": {
    "status": 400,
    "data": {},
    "errorCode": "VALIDATION_FAILED",
    "error": {
      "returnInventoryId": "'return Inventory Id' must not be empty."
    }
  }
}

檢查 meta.error——鍵名告訴您哪些欄位有問題。

業務規則與資源錯誤

這些是請求在結構上有效，但與當前資料狀態、您的帳號，或支援基礎設施衝突時由業務邏輯拋出的錯誤。每種都帶有不同的 errorCode，方便您據此分支處理。

`meta.errorCode`	Wire HTTP	`meta.status`	何時出現
`TRACKING_ALREADY_EXIST`	`200`	`400`	您提交的 `trackingNumber` 已被另一筆活躍紀錄佔用。最常見於 Create FBA shipment ——同一個 Amazon 追蹤號碼被重複提交；也可能發生在直接傳入 tracking 值的退件運貨單 / 重發(resend)建立上。`meta.error` 攜帶衝突紀錄的識別資料。
`ACCOUNT_IS_BLOCKED`	`200`	`403`	您的 API 帳號已被封鎖（例如欠款、違反條款）。所有寫入端點都會失敗，直到 Return Helper 客服解除封鎖。`meta.error.message` 含有人類可讀的原因。請聯絡 `support@returnhelper.com`。
`S3_OBJECT_NOT_FOUND_OR_NOT_PUBLIC_READ`	`200`	`404`	需要從 S3 拉取檔案的端點（通常是 VAS 附件或面單檔案）無法讀取該物件。請確認您先前上傳的檔案仍然存在且可存取。
`UPLOAD_FILE_TO_S3_FAIL`	`200`	`500`	需要上傳檔案到 S3 的端點失敗。暫時性基礎設施問題——請用相同的等冪鍵重試。
`REQUEST_CUSTOM_DOMAIN_FAIL`	`200`	`500`	呼叫自訂網域服務的面單/品牌相關端點失敗。暫時性——請重試。

認證與存取控制失敗

這些不是軟錯誤。它們會以真實的 HTTP 狀態碼回傳，因為它們在正常請求管線之前（或之外）產生。

Wire HTTP	`meta.status`	`meta.errorCode`	何時出現
`401`	`401`	`null`	`x-rr-apikey` 或 `x-rr-apitoken` 缺失、格式錯誤，或未匹配到任何活躍帳號。`meta.error.message` 為 `"Missing request header"` 或類似訊息。
`403`	`403`	`null`	拋出了 `RrForbiddenException` ——您的帳號已認證但未被授權執行此動作（例如嘗試讀取其他租戶的紀錄）。`meta.error.message` 是人類可讀的。

衝突與未找到

不常見但有可能遇到：

Wire HTTP	`meta.status`	`meta.errorCode`	何時出現
`200`	`404`	`null`	拋出了 `RrInvalidException` 或 `RrNotfoundException` ——您引用的資源（按 ID）不存在，或不屬於您的帳號。`meta.error.message` 是人類可讀的。
`409`	`409`	`null`	拋出了 `DuplicateTransactionException` ——您提交的狀態改變請求被等冪層識別為正在進行或已完成的請求的重複。`meta.error` 含 `transactionType`、`headId`、`uniqueChargeKey`、`message`。請視為無動作——原始請求已成功。

等冪金鑰失敗

以下情況適用於在寫入類端點送出 x-returnhelper-idempotency-key 標頭時，並且會以真實的 HTTP 狀態碼回傳。

Wire HTTP	`meta.status`	`meta.errorCode`	何時出現
`400`	`400`	`IDEMPOTENCY_KEY_INVALID`	金鑰不符合「1–128 個字元，且僅由英文字母、數字、`_`、`.`、`:`、`-` 組成」的規則。
`409`	`409`	`IDEMPOTENCY_REQUEST_IN_PROGRESS`	使用相同金鑰的請求仍在執行中。請待其完成後再重試。
`409`	`409`	`IDEMPOTENCY_KEY_ALREADY_USED`	使用相同金鑰的請求已在驗證時間窗內完成。請視為無動作——原始請求已處理完畢。

金鑰的作用範圍是單一帳戶加上單一 HTTP 方法與路由，因此相同的金鑰值可在不同端點重複使用而不會衝突。

建議的用戶端處理

虛擬程式碼範例：

response = call(endpoint, body)

if response.status == 401:
  reauth or alert ops
elif response.status == 403:
  surface meta.error.message — account or permission issue
elif response.status == 409:
  treat as success (idempotency replay) — do NOT retry
elif response.status == 200:
  meta = response.body.meta
  if meta.errorCode == 'VALIDATION_FAILED':
    surface meta.error map to the user — field-level messages
  elif meta.errorCode == 'TRACKING_ALREADY_EXIST':
    handle duplicate — likely already created on a previous attempt
  elif meta.errorCode == 'ACCOUNT_IS_BLOCKED':
    halt all calls, alert ops, do not retry
  elif meta.errorCode in ('UPLOAD_FILE_TO_S3_FAIL', 'REQUEST_CUSTOM_DOMAIN_FAIL'):
    retry with the same idempotency key (transient infra)
  elif meta.errorCode == 'S3_OBJECT_NOT_FOUND_OR_NOT_PUBLIC_READ':
    re-upload the source file, then retry
  elif meta.status == 200 and meta.errorCode is null:
    success — read the payload at the top level
  elif meta.status == 404 and meta.errorCode is null:
    resource not found — the ID is wrong or out of scope

correlationId 會出現在每一個回應中。請永遠把它記錄到日誌裡——這是 Return Helper 客服把某一次請求追溯到內部系統的方式。

錯誤代碼的定義位置

本頁記錄的錯誤代碼來自 ReturnRequestApiModel.RrException 命名空間中的 RrErrorCode 常數。如果您遇到本頁未列出的 errorCode 值，請將其視為未文件化的內部錯誤，並附上 correlationId 透過客服回報。

​如何閱讀本頁

​驗證失敗

​業務規則與資源錯誤

​認證與存取控制失敗

​衝突與未找到

​等冪金鑰失敗

​建議的用戶端處理

​錯誤代碼的定義位置

如何閱讀本頁

驗證失敗

業務規則與資源錯誤

認證與存取控制失敗

衝突與未找到

等冪金鑰失敗

建議的用戶端處理

錯誤代碼的定義位置