错误

错误共用一个封装结构（参见概览）。根据 code 进行分支判断，记录 meta.request_id，并将 message 视为供人阅读的英文文本。

客户端错误

代码	状态	含义和处理方法
validation_failed	400	某个字段未通过验证。field 指明该字段；details 给出说明。请修正该字段。
bad_request	400	请求完全无法读取：JSON 格式错误、Content-Encoding 数据流损坏、正文被中断。没有需要修正的字段；请检查传输过程。
validation_error	400	向禁止使用 X-Account-Id 的端点（/auth/login、/auth/refresh、/auth/swap-company、/auth/logout）发送了该标头。
cursor_expired	400	分页游标已超过 24 小时。请重新开始列表查询。
unauthenticated	401	令牌缺失或无效。请刷新会话或检查密钥。
invalid_signature	401	Webhook 签名验证失败。请参阅 Webhook。
forbidden	403	令牌有效但缺少权限。
account_context_mismatch	403	X-Account-Id 与令牌所属账户不匹配。客户端对当前公司的认知已经偏离；请从会话中重新读取。
not_found	404	资源不存在，或属于其他账户或站点。API 从不区分这两种情况。
conflict	409	状态冲突：乐观锁、唯一约束，或在当前状态下不允许的操作（例如向已合并的对话写入）。
idempotency_key_conflict	409	同一个 Idempotency-Key 被用于不同的正文。
payload_too_large	413	正文超出该端点系列的限制。
unsupported_media_type	415	Content-Type 错误。
unprocessable	422	JSON 有效，但被业务规则拒绝（例如预约时段在工作时间之外）。
storage_quota_exceeded	422	账户已达到其套餐的存储上限。details 包含 used_bytes、quota_bytes 和 requested_bytes；请释放空间或升级套餐。
rate_limited	429	请降低请求频率。遵循 Retry-After 和 details.retry_after_seconds。

服务器错误

代码	状态	含义和处理方法
internal_error	500	意外故障。重试一次，然后携带 request_id 联系支持团队。
upstream_unavailable	502	网关完全无法访问该服务。短暂等待后重试通常会成功。
service_unavailable	503	计划维护或熔断器已打开。请在 Retry-After 标头指定的时间后重试。
ai_vendor_out_of_funds	503	您的 AI 提供商因计费原因拒绝了调用（供应商返回 402 或配额 429）。请为供应商账户充值；重试无济于事。
upstream_timeout	504	服务未能及时响应。存在 retry_after 时请重试。

重试

对 429、502、503、504 和网络故障使用指数退避进行重试，并在重试时发送相同的 Idempotency-Key，确保写入操作绝不会被执行两次。除 429 外，不要重试其他 4xx 错误。