错误码与限流

API 错误统一返回：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "请求参数不符合要求",
    "requestId": "req_01J...",
    "details": {}
  }
}

HTTP	常见代码	说明
400	VALIDATION_ERROR	参数格式错误
401	UNAUTHORIZED, TOKEN_EXPIRED	未认证或令牌过期
403	FORBIDDEN, INSUFFICIENT_SCOPE	权限或 scope 不足
404	NOT_FOUND	资源不存在或不可见
409	CONFLICT	唯一性或状态冲突
429	RATE_LIMITED	请求过于频繁

OAuth 端点遵循标准错误，例如 invalid_request、invalid_client、invalid_grant、invalid_scope 和 access_denied。

限流

收到 429 时读取 Retry-After，使用带抖动的指数退避。不要自动重试 invalid_grant：授权码可能已使用，刷新令牌族也可能因重放被撤销，应重新发起授权。

提交支持请求时提供 requestId，不要提供令牌、客户端密钥、密码或完整授权 URL。