錯誤碼與重試指引

錯誤回應的結構

{
  "error": {
    "code": "invalid_parameter",
    "message": "store_id is required",
    "param": "store_id",
    "request_id": "req_01HV6N..."
  }
}

request_id 在聯繫支援時為必須。請務必含入錯誤日誌。

HTTP 狀態碼一覽

主要錯誤碼

重試指引

可以重試的條件

• HTTP 狀態為 429 或 5xx
• 網路逾時、連線錯誤
• POST 的情況務必設定 Idempotency-Key（為防止重複建立）

重試間隔（指數退避＋抖動）

function retryDelay(attempt) {
  // 1, 2, 4, 8, 16秒（最大32秒）
  const base = Math.min(Math.pow(2, attempt), 32);
  // ±25%的抖動以避免集中存取
  const jitter = base * (Math.random() * 0.5 - 0.25);
  return (base + jitter) * 1000;
}

最大重試次數

• 一般 API：最大 5 次
• 批次處理：最大 10 次
• 使用者操作起因：最大 2 次（不讓使用者久等）

429 時優先 Retry-After 標頭

HTTP/1.1 429 Too Many Requests
Retry-After: 30

→ 等 30 秒後再重試

不可重試的情況

• 4xx（429 除外）：請求本身有問題，重試幾次也一樣
• POST/PUT 未設定 Idempotency-Key 的情況：有重複建立的風險

相關指南

• 請求與回應的基本
• 速率限制與節流
• 返回開發者幫助中心