Skip to navigation

錯誤碼

錯誤回應的格式,以及完整的錯誤代碼對照表

View as Markdown

兩種錯誤格式

絕大多數的錯誤,驗證失敗、找不到資料、簽章或憑證問題,都是同一個格式:

{
"error": "invalid_page_size"
}

error 是 snake_case 字串,依代碼判斷失敗原因。極少數沒有被個別端點攔截、真正非預期的伺服器錯誤,會改用另一個格式:

{
"code": "InternalServerError",
"message": "internal error"
}

遇到這個格式代表發生了未被歸類的例外,通常是 OrderUp 端的問題,不是請求本身有錯——請聯繫 OrderUp,並附上發生的時間,方便查證。

完整對照表

狀態碼error原因
400invalid_pagepage 小於 1,或換算出的位移量超出可表示範圍
400invalid_page_sizepageSize 不在 1–100 之間
400invalid_updated_sinceupdatedSince 不是合法的 ISO-8601,或沒有帶明確時區位移/Z
400invalid_parameter查詢參數無法繫結成正確型別(例如 page=abc),或是各端點寫入邏輯裡沒有更具體對應代碼的失敗原因
400empty_batch批次 API收到空陣列或沒有 body
400internalUserId required: no default 負責業務 available建立客戶未帶 internalUserId,且該租戶沒有設定預設負責業務(這句英文本身就是代碼,不是 snake_case)
400internal_user_not_found建立或更新客戶時只送了 internalUserOuterSysCode(沒有 internalUserId),而貴租戶底下沒有未刪除的內部使用者使用這個代碼——不會退回預設負責業務,整筆不寫入。批次只有該筆失敗,字串出現在該筆的 errors 欄位,外層仍是 200
400internal_user_code_ambiguous同上,但有兩位以上的內部使用者使用同一個代碼——OrderUp 絕不會替你挑一位,請改送 internalUserId。整筆不寫入
400product_category_id_required建立商品未帶 productCategoryId(組合品沒有分類,不會回這個代碼)
400invalid_product_category_id分類不存在、不可指派(根分類),或屬於其他租戶——三種情況統一回同一個代碼
400outerSysCode is required to create a SKU建立規格未帶 outerSysCode(這句英文本身就是代碼,不是 snake_case)
400bundle SKU cannot be updated through this API/v1/skus 要更新的是組合 SKU(依 id 指定,或在指定商品下以料號命中),請改用 /v1/bundles(同樣不是 snake_case)
400outerSysCode belongs to a bundle SKU; use /v1/bundles/v1/skus 只帶料號,而這個料號只屬於組合 SKU——不會新增一般規格(同樣不是 snake_case)
400productId 0 cannot detach a SKU; omit productId to keep its product依 id 指定的規格或組合品更新(PUT /v1/skus/{id}、PUT /v1/bundles/{id},或批次項目帶 id)帶了 "productId": 0——更新不會把規格移出商品,要保留所屬商品就不要送這個欄位。沒有 id 的項目帶 0 與省略相同,不是錯誤(同樣不是 snake_case)
400invalid_status規格或組合品的 status 不是 Active、Inactive 或 GiftOnly(不分大小寫);批次只有該筆失敗
400bundle SKU stock must be set through /v1/bundles/stock/batchPOST /v1/skus/stock/batch 逐筆:skuId 指向組合 SKU。組合品的庫存請改用 POST /v1/bundles/stock/batch(同樣不是 snake_case,只出現在該列的 error 欄位,外層仍是 200)
400inventoryQuantity or isNegativeStockAllowed is requiredPOST /v1/skus/stock/batch 與 POST /v1/bundles/stock/batch 逐筆:inventoryQuantity 與 isNegativeStockAllowed 都沒帶,這一筆沒有任何要寫入的內容(同樣不是 snake_case,只出現在該列的 error 欄位,外層仍是 200)
400bundle not foundPOST /v1/bundles/stock/batch 逐筆:bundleId 查無對應組合品、屬於其他租戶,或指向一般規格,一律回這個字串(同樣不是 snake_case,只出現在該列的 error 欄位,外層仍是 200)
400SKU not foundPOST /v1/skus/stock/batch 逐筆:skuId 查無對應規格、屬於其他租戶,或 outerSysCode 沒有對到任何一般規格,一律回這個字串(同樣不是 snake_case,只出現在該列的 error 欄位,外層仍是 200)
400skuId or outerSysCode is requiredPOST /v1/skus/stock/batch 逐筆:沒有正整數的 skuId,也沒有料號(同樣不是 snake_case,只出現在該列的 error 欄位)
400bundle_components_required建立組合品未帶 components,或帶了空陣列
400component_identifier_required配方元件未帶 componentSkuId 也未帶 componentSkuOuterSysCode
400component_sku_code_ambiguous用 componentSkuOuterSysCode 反查元件規格,命中一筆以上——絕不會替你挑一筆
400component_not_found元件規格不存在,或屬於其他租戶——兩種情況統一回同一個代碼,不區分是「查無此規格」還是「規格屬於別的租戶」,避免洩漏元件序號屬於別的租戶
400component_cannot_be_a_bundle元件規格本身是組合品型別,不允許巢狀組合
400component_duplicated同一份配方裡出現重複的元件規格
400invalid_component_quantity元件用量(quantity)不是正數、超出可表示的數值範圍,或四捨五入到小數 4 位後不大於 0
400component_self_reference更新組合品的配方時,元件指向這個組合品自己
400product_type_conflict/v1/bundles 的料號屬於一般規格(只帶料號時比對整個租戶,帶 productId 時比對該商品底下)——不會被視為更新,也不會新增,整筆失敗。一般規格請改用 /v1/skus
400invalid_price規格或組合品的 price/sellPrice 超出 0 至 9999999.99 的範圍
400invalid_quantity_precision組合品的 quantityPrecision 不在 0 至 4 之間
400missing_key點數/合約額度批次同步:companyId 與 companyCode 皆未提供,或 companyCode 為空字串
400missing_balance點數額度批次同步未帶 balance——這是必填的絕對值欄位,省略不會保留原值,也不會被序列化預設值 0 悄悄歸零
400invalid_balance點數額度批次同步的 balance 為負值
400missing_credit_limit合約額度批次同步未帶 creditLimit,規則鏡像 missing_balance
400invalid_credit_limit合約額度批次同步的 creditLimit 為負值
400invalid_memo點數/合約額度的 memo 超過 200 字元——用的是這個代碼,不是 memo_too_long
400company_code_ambiguous用 companyCode 反查客戶,命中一筆以上——點數/合約額度批次同步共用,OrderUp 絕不會替你挑一筆。客戶總部的總部或子客戶代碼(parentCompanyCode、subCompanyCodes)命中一家以上時也是這個字串,且在客戶總部端點是 400
400company_not_found客戶總部的總部或子客戶(以 id 或代碼指定)不存在、已刪除,或屬於其他租戶——因為出問題的是 body 裡的成員而不是網址上的資源,這裡是 400,不是額度端點的 404。錯誤不會指出是哪一個 id 或代碼有問題
400sync_failed點數/合約額度批次同步逐筆寫入時發生非預期例外,是這兩支端點自己的逐筆版「未分類錯誤」——只出現在該筆的 error 欄位,不會反映在外層 HTTP 狀態碼(外層仍是 200)
400{field}_too_long有送出的欄位超過長度上限;每個欄位各自的上限與這個代碼,見該欄位在 API 規格裡的說明
400account_required/name_required/email_required/password_required建立後台使用者缺少對應的必填欄位;建立客戶帳號時 account_required/name_required/password_required 同樣適用(客戶帳號的 email 選填);name_required 也用於客戶總部的群組名稱空白(建立,或更新時有給 name 但為空白)
400account_already_used建立後台使用者或客戶帳號,account 在同租戶內已被使用(不分大小寫)——客戶帳號同樣以整個租戶為範圍,另一家客戶用過的帳號也算重複
400invalid_account_format建立客戶帳號,account 不是 3–50 個英文字母、數字或連字號(-),也不是有效的電子郵件格式
400role_id_required建立客戶帳號未帶 roleId(或帶 0)
400invalid_role_idroleId 不存在或屬於其他租戶;建立後台使用者時省略 roleId 也是這個代碼(建立客戶帳號時省略則是 role_id_required)
400invalid_status更新後台使用者,或建立/更新客戶帳號,status 不是 Active 或 Inactive(規格與組合品的 status 見上方同名代碼)
400key_requiredPUT /v1/internal-users/batch 逐筆:id 與 outerSysCode 都沒給(沒有 id 時,outerSysCode 只有空白也算沒給)。只出現在該筆的 errors 欄位,外層仍是 200
400ambiguous_outer_sys_codePUT /v1/internal-users/batch 逐筆:同租戶內有兩位以上的使用者用同一個 outerSysCode,OrderUp 絕不會替你挑一位,該筆不會寫入。只出現在該筆的 errors 欄位,外層仍是 200
400invalid_settlement_type建立或更新客戶時,settlementType 不是 Cash 或 Monthly(大小寫敏感)
400invalid_payment_method_mode建立或更新客戶時,paymentMethodMode 不是 Inherit 或 Specify(大小寫敏感)
400payment_method_mode_required建立或更新客戶時,送了 paymentMethods(包含空陣列)卻沒送 paymentMethodMode——兩個欄位須成對寫入
400payment_methods_requiredpaymentMethodMode 為 Specify,但 paymentMethods 省略、空陣列,或去掉空白元素後為空——Specify 必須在同一個請求帶非空清單
400payment_methods_not_allowedpaymentMethodMode 為 Inherit,但 paymentMethods 帶了非空清單
400invalid_payment_methodpaymentMethods 含不合法的元素:None、字面的 CustomOffline、其他租戶或已刪除的自訂 key、格式不符的字串等。可用的 key 見 GET /v1/payment-methods
400monthly_settlement_not_allowedpaymentMethods 含 MonthlySettlement——月結是結帳條件,請改用 settlementType
400name_too_long客戶總部的群組名稱去掉前後空白後超過 50 字元(其他資源的 name 超長同樣是這個字串,見 {field}_too_long)
400parent_company_required建立客戶總部時,parentCompanyId 與 parentCompanyCode 都沒給
400parent_already_headquarters客戶總部的總部客戶已經是另一個群組的總部
400company_already_in_group客戶總部的總部客戶或任一子客戶,已經屬於另一個群組
400sub_company_is_headquarters客戶總部的任一子客戶,是另一個群組的總部客戶
401unauthorized簽章、時間戳記或 nonce 其中一項驗證沒有通過
403forbidden簽章驗證通過,但你的憑證未開通此項操作
404not_foundid 不存在、屬於其他租戶,或指向錯誤的資源型別(例如一般規格端點查到組合 SKU、組合品端點查到一般規格)——這幾種情況無法從回應內容區分;組合品寫入的 productId 不是租戶內既有的商品時也是這個代碼
404查無客戶資料PUT /v1/companies/{id} 找不到對應客戶時的 404 body;POST /v1/companies/batch 逐筆依 id 更新卻查無這筆客戶時,同一句話也會原樣出現在該筆的 errors[](此時外層 HTTP 狀態碼仍是 200,不是 404)
404商品不存在同上,對應 PUT /v1/products/{id}/POST /v1/products/batch
404SKU 不存在同上,對應 PUT /v1/skus/{id}/POST /v1/skus/batch;建立或更新規格時 productId 指向不存在的商品也是這句話
404company_not_found點數/合約額度的查詢或批次同步找不到對應客戶,或客戶帳號端點(/v1/companies/{id}/users)找不到網址上的客戶——這些掛在客戶底下的端點用的是獨立的第二套 404 代碼,見下方「404」一節
409last_active_admin這個後台使用者是租戶目前唯一還能登入的系統管理員,這次寫入會讓租戶失去所有可登入的系統管理員,因此被拒絕
409last_active_boss這個客戶帳號是客戶目前唯一生效中的 Boss,這次寫入(改成其他角色或設為 Inactive)會讓客戶失去所有生效中的 Boss,因此被拒絕

客戶的結帳條件與付款方式有七個字串:invalid_settlement_type、invalid_payment_method_mode、payment_method_mode_required、payment_methods_required、payment_methods_not_allowed、invalid_payment_method 與 monthly_settlement_not_allowed。POST /v1/companies/batch 逐筆寫入時,這七個字串都出現在該筆的 errors 欄位,外層仍是 200。

401:驗證失敗

401 一律代表簽章、時間戳記或 nonce 其中一項驗證沒有通過,從呼叫端角度完全無法區分是哪一項——回應本身不會說明原因,避免洩漏線索給攻擊者。完整的逐項排查清單見「驗證與簽章」最後一節,這裡不重複。

403:憑證未開通此項操作

簽章驗證通過,但你的憑證未開通此項操作。請聯繫 OrderUp 開通。

404:兩套詞彙並存

GET 單筆端點與庫存、規格價格、組合品價格查詢的 404 一律是 { "error": "not_found" }——id 不存在、屬於其他租戶,或指向錯誤的資源型別(例如用一般規格的價格端點查一顆組合 SKU),都回同一個代碼,無法從回應內容區分是哪一種。

判斷「找不到」請只看 HTTP 狀態碼,不要比對 error 字串本身。更新客戶/商品/規格(PUT /v1/companies/{id}、PUT /v1/products/{id}、PUT /v1/skus/{id})如果 id 不存在或屬於其他租戶,回傳的 404 body 帶的是該資源專屬的簡短說明文字(例如「查無客戶資料」),不是固定的 not_found 代碼;後台使用者的更新端點則一律回傳 not_found。不論哪一種,狀態碼都是 404,依狀態碼判斷比依 error 字串判斷可靠。

⚠️ 這條「依狀態碼判斷」的建議只適用於單筆端點。「查無客戶資料」/「商品不存在」/「SKU 不存在」這三句話也會原樣出現在 POST /v1/companies|products|skus/batch 逐筆的 errors[] 裡(依 id 更新但查無這筆資料時),此時外層 HTTP 狀態碼固定是 200,看不出任何 404——批次情境下只能看那一筆的 status 是不是 failed,不能靠狀態碼。

點數額度與合約額度家族是刻意的例外:GET /v1/companies/{id}/point-quota、GET /v1/companies/{id}/credit-quota,以及兩者的批次同步端點,找不到對應客戶時一律回傳 404 company_not_found,不是 not_found。這是這個 family 自己的第二套 404 詞彙,不是遺漏——額度 family 內部一致(同一個字串也是批次逐筆失敗時的 error),只看這一組端點的整合者從頭到尾只會看到一種詞彙。客戶帳號端點(/v1/companies/{id}/users 與其下的單筆端點)同樣掛在客戶底下,網址上的客戶找不到時也回傳 404 company_not_found;客戶存在但帳號找不到(包括帳號屬於另一家客戶)時才是 404 not_found。其餘所有 family(客戶、客戶總部、商品、規格、組合品、規格價格、組合品價格、後台使用者)一律用 not_found。

客戶(GET /v1/companies/{id})本身找不到時仍然是 not_found,不是 company_not_found——第二套詞彙的 404 只出現在掛在客戶底下的端點(點數額度、合約額度、客戶帳號),不影響客戶主檔本身的 404。

客戶總部端點也會用到 company_not_found,但那是 400:找不到的是請求 body 裡指定的總部或子客戶,不是網址上的資源。客戶總部本身(GET/PUT/DELETE /v1/company-groups/{id})找不到時是 404 not_found。

409:狀態衝突(僅後台使用者與客戶帳號)

409 last_active_admin 只會出現在 PUT /v1/internal-users/{id};PUT /v1/internal-users/batch 遇到同樣的情況時,不會回傳 409,而是在該筆的 errors 裡帶同一個字串,外層仍是 200。請求本身格式正確,衝突的是系統目前的狀態:這個使用者是租戶目前唯一還能登入的系統管理員,若這次寫入把他改成非管理員角色、或把狀態設為 Inactive,租戶會失去所有可登入的系統管理員——這支端點會拒絕該次寫入,而不是靜默放行。

下一步

409 last_active_boss 是同一類的保護,只會出現在 PUT /v1/companies/{id}/users/{userId}:前台有一整批功能只開放給 Boss 角色(例如管理同公司的帳號、查看全公司的訂單),後台為客戶代客下單也需要客戶有 Boss。若這個帳號是客戶目前唯一生效中的 Boss,把他改成其他角色、或把狀態設為 Inactive 會被拒絕;請先把另一個帳號改為 Boss。本來就沒有生效中 Boss 的客戶不受這條限制。