处理 API 错误和重试

在读取响应为成功之前，始终检查 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、客户端密钥、访问令牌、刷新令牌和私密提示内容。