处理 API 错误和重试
诊断 ShareAI 身份验证、范围、模型访问和可用性错误，避免重复写入或不安全的刷新重试。
本页面内容
在读取响应为成功之前，始终检查 HTTP 状态。ShareAI 服务可能返回不同的错误封装：推理可能提供 error.code，OAuth可能提供 error 和 error_description，控制台路由可能返回 code, message 和 data.status.
| 状态 | 典型含义 | 恢复 |
|---|---|---|
| 带有错误对象的200状态 | 当前聊天端点中无设备可用结果。 | 检查 error.code，不要将其呈现为助手答案。 |
| 400 | 无效请求或 OAuth 授权。 | 修正请求体、参数、回调或过期/已使用的代码。 |
| 401 | 缺失、过期或无效的身份验证。 | 检查凭证；仅刷新有效的OAuth授权。 |
| 402 | 信用额度或适用余额不足。 | 在重试之前检查所选账户余额。 |
| 403 | 范围、所有权、角色或启用状态被拒。 | 检查记录的权限边界。 |
| 404 | 未知资源或不支持的网关路由。 | 检查主机、路径和资源标识符。 |
| 409 | 状态或修订冲突。 | 读取当前状态并重新考虑更改。 |
| 429 | 请求或并发限制。 | 遵守 Retry-After 并使用有限的回退。 |
| 500 / 502 / 503 | 服务器或上游可用性故障。 | 保持重试次数有限；保留诊断标识符。 |
限制重试读取#
对于读取的临时故障，等待并逐步增加延迟和抖动，当 Retry-After 存在时遵守，并在定义的尝试次数或时间预算后停止。当数据不可用时向用户显示，而不是静默循环。
谨慎处理写入#
当结果未知时，不要自动重复价格更新、模型创建或共享命令。首先读取资源或命令状态。仅在文档支持的端点上使用 Idempotency-Key，例如协议更改。
刷新令牌为一次性使用#
刷新轮换需要在后端进行每次授权锁定。盲目重试已使用的刷新令牌可能会撤销授权。参见 安全令牌刷新.
支持请求中应包含的内容#
包括端点、HTTP 状态、错误代码、时间和响应/任务标识符（如果可用）。移除 Authorization 头、cookies、客户端密钥、访问令牌、刷新令牌和私密提示内容。
最近更新于 9 月 15, 2026