错误处理与重试 | 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、版本。