錯誤碼一覽

API 回應的 code

錯誤碼	HTTP	意思	建議處理
`S0000`	200	成功	—
`A0001`	401	未授權：token 缺少、格式錯誤、不是這個網域目前的 token，或網域沒有開啟 API 串接	確認 header 是 `Authorization: Bearer <token>`，以及用對了測試或正式環境的 token
`A0002`	401	token 已過期：超過到期日（新產生的 token 預設一年），或重新產生後已超過保留期限的舊 token	到 CRM「總設定」→「開發者」重新產生 token 並更新伺服器設定
`V0001`	400	請求參數錯誤	依 `message` 修正後重送。欄位驗證錯誤的訊息不含欄位路徑，請對照 API 參考逐欄檢查
`V0002`	400	狀態不允許：金流尚未開通，或交易、定期定額目前的狀態不能做這個動作	先查詢目前狀態再決定
`V0003`	400	超過單筆最高金額（200,000 元以上需要開通高額交易）	拆成多筆，或聯絡應援開通
`V0004`	400	只開指定付款方式（`strictPaymentMethods: true`）時沒有帶付款方式清單	帶上非空的 `allowedPaymentMethods`
`V0005`	400	只開指定付款方式時，清單裡有網域還沒開通的方式	看 `message` 是哪一種，先開通或從清單拿掉
`V0006`	400	只開指定付款方式時，清單裡沒有任何方式接受這個金額	加上信用卡，或調整金額
`V0007`	400	只開指定付款方式時，幣別不是新台幣	改用 `TWD`
`T0001`	400	交易失敗（一般原因）	請消費者換卡或稍後再試
`T0002`	400	安全碼錯誤	請消費者確認卡片資料
`T0003`	400	卡片過期	請消費者換卡
`T0004`	400	額度不足	請消費者換卡或聯絡發卡銀行
`T0005`	400	發卡銀行拒絕授權	請消費者聯絡發卡銀行或換卡
`T0009`	400	網域的信用卡設定還不能做免 3D 扣款（缺少特店代號）	請聯絡應援
`T0010`	400	同一個 token 短時間內被明確拒絕太多次，這次沒有送出扣款	不要再用這個 token 重試。請消費者確認卡片或重新綁卡；一段時間後會自動恢復
`R0001`	400	退款失敗	先查詢交易狀態。之後重試都回 `V0002` 時，代表退款結果需要人工確認，請聯絡應援
`K0001`	400	風控拒絕：個人身分商家的當月累計或單筆金額超過門檻	回應的 `detail.subCode` 說明原因，請聯絡應援
`C026`	409	付款結果不明，回應帶 `"retryable": false`	不要重試，也不要換一筆新訂單重扣。帶了 `Idempotency-Key` 時，用同一把 key 重送是安全的。稍後用查詢交易或訂單編號查詢確認；久未確定請聯絡應援
`I0001`	422	同一把 Idempotency-Key 用在不同的請求（method、路徑或 body 不同）	確認是否真的要建立新的請求；是的話換一把新的 key
`I0002`	409	同一把 Idempotency-Key 的第一次請求還在處理	稍後用同一把 key 重送，或改用查詢 API 確認結果
`I0003`	409	同一把 Idempotency-Key 的第一次請求已開始扣款或退款，之後中斷、沒有結果。回應帶 `detail.resourceId`（交易或定期定額編號）	不要換 key 重送。用 `detail.resourceId` 或訂單編號查詢結果，久未確定請聯絡應援
`C0000`	400	換卡頁：其他原因，包含網域的信用卡不是由 CyberSource 收單	目前不支援換卡時，請取消舊的定期定額，請消費者重新訂閱
`C0001`	400	換卡頁：找不到定期定額，或不是 Payment API 建立的	確認 `S` 開頭的定期定額編號
`C0002`	400	換卡頁：定期定額目前的狀態不能換卡	查詢定期定額狀態
`C0003`	400	換卡頁：這一期正在扣款	稍後再試
`C0004`	409	換卡頁：已有進行中的換卡頁	等 `detail.expiresAt` 之後再建立，或沿用進行中的換卡頁
`C0008`	400	換卡頁：網域不接受這種卡	請消費者換一張卡
`C0010`	409	換卡頁：同一個 `requestId` 已建立過換卡頁（不會再給 `checkoutUrl`）	沿用第一次回應保存的 `checkoutUrl`；連結遺失時，等原換卡頁到期後再用新的 `requestId` 建立
`C0011`	400	換卡頁：網域目前不能收信用卡	請聯絡應援
`C0012`	400	換卡頁：風控拒絕	請聯絡應援
`C0013`	400	換卡頁：`successUrl` 或 `failureUrl` 不合法	改用 `https://` 開頭、不含帳號密碼的網址
`F0001`	500	系統錯誤或未分類的錯誤	看 `message`：`Invalid date`（日期參數錯誤）、`Pagination parse failed`（`page` 分頁標記無效）、`Current charged amount too low`（退款時網域待撥款金額不足）請依原因處理；正式環境的其他系統錯誤 `message` 一律是 `SYSTEM_ERROR`、不帶 `detail`，請稍後重試，建立交易類的請求重試前先查詢

處理原則見錯誤處理。

結帳頁導回的 payment_error

消費者付款失敗或逾時時，會被導回你的 failureUrl，網址加上 payment_error=<代碼>，例如 https://shop.example.com/payment/failure/A001?payment_error=T0004。

錯誤碼	HTTP	意思	建議處理
`V0002`	導回參數	結帳逾時、交易已處理過或找不到交易；未歸類的錯誤也是這個值	重新建立交易
`V0003`	導回參數	付款結果尚未確定。和 API 回應的 `V0003` 意思不同	等付款通知，或稍後查詢交易
`T0001`	導回參數	付款失敗，包含 3D 驗證失敗	請消費者換卡或稍後再試
`T0002`	導回參數	安全碼錯誤	請消費者確認卡片資料
`T0003`	導回參數	卡片過期	請消費者換卡
`T0004`	導回參數	額度不足	請消費者換卡
`T0005`	導回參數	發卡銀行拒絕	請消費者聯絡發卡銀行或換卡
`Y003`	導回參數	綁卡頁已逾時（10 分鐘）	重新建立綁卡頁

導回的代碼只用來顯示訊息給消費者，請以付款通知或查詢結果為準。
LINE Pay 付款失敗或取消時，導回 failureUrl 不帶 payment_error。

其他 HTTP 狀態

HTTP	什麼時候	body
403	正式環境的呼叫來源 IP 還沒綁定，見固定 IP 白名單	只有 `message` 欄位（通常是 `Forbidden`），沒有 `code`
404	路徑不存在	純文字 `Not Found`
405	不支援的 HTTP method	純文字 `Method Not Allowed`
504	處理超過 29 秒。請求可能已經成功，先查詢再決定要不要重送	—