錯誤處理與重試 | AppForges Developer Center

錯誤結構

網關錯誤包含嵌套 error，其中 code 是數字、status 是狀態名稱，details 包含診斷信息。HTTP 狀態、服務端錯誤 code 和 ErrorInfo 的 reason 是不同維度，不能互換。業務端點的錯誤詳情以實際響應為準。

{
  "error": {
    "code": 401,
    "status": "UNAUTHENTICATED",
    "message": "Missing credential",
    "details": [{
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "MISSING_CREDENTIAL",
      "domain": "iam.appforges.com"
    }]
  }
}

HTTP	已驗證 reason	處理
401	`MISSING_CREDENTIAL`	提供合法憑據
401	`OAUTH_TOKEN_INVALID`	檢查用戶 token、issuer 與有效期
404	`user_mismatch`	檢查資源路徑和主體，不重複相同請求
429	`RATE_LIMIT_EXCEEDED`	遵守 `Retry-After`

診斷標識從響應 X-Request-Id / X-Trace-Id 讀取；SDK錯誤對象保留狀態、reason、請求ID與重試等待，不應只解析 message。不要記錄完整憑據或用戶響應。

重試邊界

正式SDK默認最多兩次額外重試，429優先等待 Retry-After；SDK同時處理可重試網絡/服務端錯誤。401/403/404先修復請求或授權。取消信號或context也應結束等待。首次接入可將重試設為0，示例見快速開始。

寫操作僅在對應端點支持冪等、且重試複用同一個 X-Idempotency-Key 時考慮重試。不同業務動作使用不同key，不為每次重試重新生成key。

X-Idempotency-Key: example-stable-operation-key

key不會將任意寫操作自動變成冪等；去重存儲、保留期限和payload衝突處理以端點合同為準，不存在通用的24小時網關結果緩存承諾。不要在SDK外再套一層無界重試。

限流信息

讀取 X-RateLimit-Limit-Short / Remaining-Short / Reset-Short 和對應Long窗口；Reset為Unix時間。額度以實際響應為準，429通常也有這些頭。遵守服務端等待，並限制自己的併發和重試預算。

參見SDK、版本。