錯誤處理

錯誤回應

{ "code": "V0001", "data": {}, "message": "PRODUCT_AMOUNT_NOT_MATCH" }

你收到	可以重試嗎	怎麼做
400 `V0001`	不行	依 `message` 修正參數
400 `V0002`	不行	先查詢目前狀態
400 `T0001`～`T0005`	不要用同一張卡立刻重試	請消費者換卡或聯絡發卡銀行
400 `T0009`	不行	網域的信用卡設定問題，聯絡應援
400 `T0010`	不行	同一個 token 短時間內被拒絕太多次。不要繼續重試，請消費者確認卡片或重新綁卡
400 `K0001`、`V0003`	不行	聯絡應援
401 `A0001`、`A0002`	不行	檢查 token；`A0002` 是 token 過期，要重新產生。見驗證與 token
403（沒有 `code`）	不行	IP 還沒綁定，見固定 IP 白名單
409 `C026`	不行	付款結果不明，見下方
409 `I0002`	可以，稍後用同一把 key	第一次的請求還在處理
409 `I0003`	不行	用 `detail.resourceId` 或訂單編號查詢結果，不要換 key 重送
422 `I0001`	不行	同一把 key 用在不同的請求。確認真的要建立新的請求再換 key
500 `F0001`	看情況	先看 `message`，見下方
504、逾時、連線中斷	先查再說	請求可能已經成功，見下方

回應是：

{ "code": "C026", "data": {}, "message": "PAYMENT_STATUS_UNKNOWN", "retryable": false }

扣款可能已經發生，只是結果還沒確定。交易會停在 charging：

不要不帶 key 重送，也不要建立新的訂單再扣一次。用同一把 Idempotency-Key 重送是安全的，會回 409 I0002 或 I0003，不會再扣款。
稍後用訂單編號查詢確認交易狀態。
一段時間後仍是 charging，請帶交易編號聯絡應援。

API 最多處理 29 秒，超過會回 504，但後面的處理可能還在進行，甚至已經成功。

有帶 Idempotency-Key 時，可以直接用同一把 key 重送：已經成功的會拿到原本的回應，還在處理的回 409 I0002。沒有帶 key 時：

`message`	原因	怎麼做
`Invalid date`	查詢列表的 `start`、`end` 格式錯誤，或只帶一個	修正參數
`Pagination parse failed`	`page` 分頁標記無效	用上一頁回傳的原值
`Current charged amount too low`	退款時，網域尚未撥款的金額低於 200 元	聯絡應援
JSON 解析錯誤	body 不是合法的 JSON	修正 body
其他（正式環境固定是 `SYSTEM_ERROR`，不帶 `detail`）	系統錯誤	查詢類可以稍後重試；建立交易、退款類請先查詢再決定

驗證失敗回 400 V0001，message 會列出所有不符合的規則，例如 must have required property 'productDetails'; must be >= 1。
message 不一定有欄位名稱，請對照 API 參考的欄位表逐一檢查。
規格裡沒有的欄位會被忽略，不會報錯。欄位名稱拼錯時，常見的現象是「送了但沒效果」或「必填欄位缺少」。

message	原因
`must have required property 'productDetails'`	沒帶商品明細。所有建立交易的 API 都要帶
`PRODUCT_AMOUNT_NOT_MATCH`	品項「數量 × 單價」的合計不等於 `amount`
`USER_NAME_AND_EMAIL_REQUIRED`	網域有開通電子發票，但沒帶 `userName` 或 `userEmail`
`INVALID_PARAMS`	`merchantId` 和 token 的網域不同；或查詢的交易不屬於你的網域
`PAYMENT_SERVICE_NOT_ACTIVATE`	網域的金流服務還沒開通
`LINE_PAY_NOT_ACTIVE`	帶了 `linePay`，但 LINE Pay 還沒開通
`START_DATE_MUST_GREATER_THAN_TODAY`	`startDate` 早於今天（用 token 建立定期定額時，今天也不行）
`must match format "uri"`	`successUrl` 或 `failureUrl` 不是完整網址，少了 `https://`

請提供：網域名稱、環境（測試或正式）、呼叫時間、端點、交易編號或 orderId，以及完整的錯誤回應。不要附上 token。