Service API 接入 · 06
错误码
接口错误以 HTTP 状态码 + JSON 体形式返回（注意：不是 OpenAI 的 {"error": {...}} 嵌套结构，而是 FastAPI 的 {"detail": "..."} 形式）：
json
{ "detail": "Invalid API key" }| 状态码 | detail 示例 | 处理建议 |
|---|---|---|
400 | "No user message found" | messages 数组里没找到 role=user 的项 |
400 | "There was an error parsing the body" | 请求体被网关层判定为空 / 格式异常（常见于 PowerShell 单引号问题，建议改用 -d @body.json） |
401 | "Missing API key" / "Invalid API key" | 检查 Authorization 头 |
403 | "Service not published" | service 被管理员下架，联系部署方 |
404 | "Conversation not found" | 传入的 conversation_id 不存在或不属于当前 service |
422 | [{"type":"json_invalid","loc":["body",N],"msg":"JSON decode error",...}] | 请求体被 FastAPI 校验失败（合法 HTTP 但 JSON 解析错 / 字段不符 schema）。注意 detail 是数组，不是字符串 |
5xx | 各种 | 服务端问题，重试或联系部署方 |
400 vs 422 区分：完全打不开的 JSON 一般是
422（FastAPI 校验拦截）；通过校验但语义不符（如缺 user 消息）才是400。客户端建议两种都按"请求方写错了"处理，不要重试。
流式中错误
流式响应中如果中途出错，/chat/completions（OpenAI 兼容） 会：
- 追加一个 chunk：
delta.content = "\n\n[Error: <错误信息>]" - 紧接着发
finish_reason: "stop"+data: [DONE] - 不抛出 HTTP 错误码（连接已经在 200 状态下建立）
/chat（自定义 SSE） 出错时则发 data: {"type": "error", "content": "..."}，不会再发 done。客户端要把 error 也当作终止信号处理。