回應碼只是第一層，code 才是原因

請求成功。回應內容就是這支端點定義的資料。

• GET／PATCH 成功
• POST 成功但不建立新資源（例如驗證碼核對）

直接解析 JSON。文件頁的「回應」區塊就是這個形狀。

已建立資源，而且回應會帶新資源的 id。

• 註冊、建立商品、建立 webhook、建立收款意圖／結帳

把回應裡的 id 存起來（user_id／intentId／orderId），後續呼叫要用。

請求本身有問題：JSON 壞掉、必填缺漏、金額或狀態不合法。

• body 不是合法 JSON → code: "invalid_json"
• 必填欄位缺漏或型別錯
• 金額為負、超過上限，或退款金額大於可退餘額（pay_refund_amount_invalid）
• 意圖狀態不允許這個動作（pay_bad_status）

不要盲目重試。先看 code 與 error，修正請求後再送。

沒有帶憑證，或憑證無效／過期。

• 缺少 X-HSystem-Token 或 Authorization
• access_token 過期
• refresh_token 已撤銷 → 重新登入
• code: "login_required"（需要先走登入頁）
• code: "mfa_invalid"（MFA 驗證碼錯誤）

先用 refresh_token 換新 token；換不到就重新走登入流程。不要用同一組憑證重試。

已通過認證，但這個身分不能做這件事。

• 服務未在 App 啟用（pay_service_disabled、email_not_registered）
• 需要 App Secret 但你只帶了使用者 token（pay_refund_app_secret_required、pay_order_app_only）
• 這不是你的資源（pay_intent_forbidden、pay_order_forbidden）
• scope／權限不足（Agent Token 少 pay:live 等）
• 功能未開放（mfa_unavailable）

這是設定問題，不是重試問題。引導使用者回開發者控制台啟用服務或補 scope。

路徑不存在，或路徑／資源 id 找不到對應資料。

• 打錯網址（error: "找不到這個接口"）
• pay_intent_not_found／pay_order_not_found／pay_price_not_found
• path 參數用了不存在的 id

檢查 base URL 與 path 參數。文件頁的 Playground 有一樣的網址可以對照。

請求合法，但與目前狀態衝突：重複建立、併發，或餘額不足。

• email_already_registered：這個 Email 已經註冊
• pay_race：同一筆意圖／訂單被別人搶先改狀態
• pay_refund_conflict：同時兩筆退款搶同一筆餘額
• hcoin_insufficient：HCoin 餘額不足（開發者操作）
• already_published／already_friends／already_unlocked

重新讀取最新狀態再決定。退款請重讀 refundableCents；HCoin 不足要先去控制台加值。

被限流或超出方案配額。回應會帶 code、dimension、limit。

• code: "rate_limited"、dimension: "rpm" → 每分鐘請求數超限
• dimension: "daily" → 當日請求數超限
• dimension: "ip_rpm" → 同一 IP 太密集
• error: "超出方案配額" → 該服務維度的免費額＋加購用完

指數退避重試（建議 1s → 2s → 4s，最多 3 次）；持續 429 就去看控制台的用量與方案，不要縮短間隔硬撞。

伺服器端錯誤，不是你的請求格式問題。

• 未預期的例外（error: "伺服器錯誤"）

退避重試 1–2 次；仍失敗請把當下時間、端點、請求 body 與回應貼到開發者控制台回報。

這支端點是骨架，功能還沒實作。文件頁會標 BETA。

• google_oauth_not_configured：平台尚未配置 Google 憑證
• mfa_unavailable：開了 MFA 但沒有可用的驗證管道

不要接進正式流程。改看文件上標示 ga 的替代端點。