错误码与状态码

HTTP 状态码

成功

状态码	含义	使用场景
`200`	OK	GET/PATCH 成功
`201`	Created	POST 创建成功
`204`	No Content	DELETE 成功、无返回体的操作

客户端错误

状态码	含义	使用场景
`400`	Bad Request	业务逻辑拒绝（如验证码错误）
`401`	Unauthorized	Token 无效或过期
`402`	Payment Required	余额不足（狐币不够）
`403`	Forbidden	无权限或账号被封禁
`404`	Not Found	资源不存在或无权访问
`409`	Conflict	资源冲突（如重复创建、并发修改冲突）
`413`	Payload Too Large	文件/配额超限
`422`	Unprocessable Content	请求体验证失败
`429`	Too Many Requests	请求频率超限

服务端错误

状态码	含义	使用场景
`500`	Internal Server Error	服务端内部错误
`502`	Bad Gateway	上游 AI 服务返回错误或不可达
`503`	Service Unavailable	服务配置错误
`504`	Gateway Timeout	上游 AI 服务响应超时
`529`	Site Overloaded	上游 AI 服务过载/限流（非标准状态码）

529 状态码说明

529 不是标准 HTTP 状态码。当上游 AI 服务返回限流响应时，系统使用此状态码区分：

429 = **你（调用方）**请求太频繁
529 = 上游 AI 服务太忙，不是调用方的问题

客户端收到 529 时建议稍后重试。

错误响应格式

REST API

json

{
  "detail": "错误描述信息"
}

验证错误（422）

json

{
  "detail": [
    {
      "loc": ["body", "phone"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

WebSocket 错误码

Close Codes

Code	含义
`1000`	正常关闭
`1001`	服务端关闭
`4001`	认证失败
`4008`	用户被踢出
`4009`	资源冲突（已有连接/锁丢失）

消息错误码

通过 error 类型消息推送：

json

{
  "type": "error",
  "message": "用户友好的错误描述",
  "code": "error_code",
  "request_id": "关联请求ID"
}

错误码	含义	典型场景
`character_busy`	角色正在处理	上一次补全未完成时再次请求
`llm_config_error`	AI 模型配置错误	模型参数超出限制
`llm_api_error`	AI 模型调用失败	上游服务返回错误
`llm_timeout`	AI 模型调用超时	上游服务响应超时
`conversation_locked`	对话被锁定	其他操作正在进行
`invalid_tool_call_id`	工具调用 ID 无效	ID 不存在或状态不匹配
`no_user_message`	无用户消息	对话为空时请求补全
`insufficient_balance`	余额不足	狐币不够支付本次操作
`permission_denied`	无访问权限	操作非自有资源
`rate_limited`	发送频率过高	消息发送速率超限
`internal_error`	服务内部错误	服务端未预期异常