跳轉到主要內容
此頁面由 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 401/403/409——這些情況發生在回應信封被套用之前，或代表真正的 HTTP 語意。

​
驗證失敗

幾乎每個寫入端點都會經過 FluentValidation。在此被攔截的任何內容——缺少必填欄位、值超出範圍、國家代碼無效、批次超出上限、以 Custom(...) 檢查表達的業務規則違反——都會歸併到同一個錯誤代碼：
Wire HTTPmeta.statusmeta.errorCodemeta.error
200400VALIDATION_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.errorCodeWire HTTPmeta.status何時出現
TRACKING_ALREADY_EXIST200400您提交的 trackingNumber 已被另一筆活躍紀錄佔用。最常見於 Create FBA shipment ——同一個 Amazon 追蹤號碼被重複提交；也可能發生在直接傳入 tracking 值的退件運貨單 / 重發(resend)建立上。meta.error 攜帶衝突紀錄的識別資料。
ACCOUNT_IS_BLOCKED200403您的 API 帳號已被封鎖（例如欠款、違反條款）。所有寫入端點都會失敗，直到 Return Helper 客服解除封鎖。meta.error.message 含有人類可讀的原因。請聯絡 support@returnhelper.com。
S3_OBJECT_NOT_FOUND_OR_NOT_PUBLIC_READ200404需要從 S3 拉取檔案的端點（通常是 VAS 附件或面單檔案）無法讀取該物件。請確認您先前上傳的檔案仍然存在且可存取。
UPLOAD_FILE_TO_S3_FAIL200500需要上傳檔案到 S3 的端點失敗。暫時性基礎設施問題——請用相同的等冪鍵重試。
REQUEST_CUSTOM_DOMAIN_FAIL200500呼叫自訂網域服務的面單/品牌相關端點失敗。暫時性——請重試。

​
認證與存取控制失敗

這些不是軟錯誤。它們會以真實的 HTTP 狀態碼回傳，因為它們在正常請求管線之前（或之外）產生。
Wire HTTPmeta.statusmeta.errorCode何時出現
401401nullx-rr-apikey 或 x-rr-apitoken 缺失、格式錯誤，或未匹配到任何活躍帳號。meta.error.message 為 "Missing request header" 或類似訊息。
403403null拋出了 RrForbiddenException ——您的帳號已認證但未被授權執行此動作（例如嘗試讀取其他租戶的紀錄）。meta.error.message 是人類可讀的。

​
衝突與未找到

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

​
建議的用戶端處理

虛擬程式碼範例： 
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 透過客服回報。