接入错误与排查
从HTTP状态、任务状态和业务身份逐步定位失败，避免重复执行与错误放行。
先确定失败发生在提交、排队执行、身份核验、业务权限还是结果展示。HTTP返回成功、任务执行完成和业务结果正确是不同检查点；重新发送请求前，先判断上一次是否已经产生实际业务动作。
先保存最小排障信息
保留操作时间、使用的入口、HTTP状态、安全错误码、error.trace_id以及对话ID和任务ID。同步接口还提供X-Hive-Conversation-Id与X-Hive-Run-Id，异步提交直接返回任务ID。
不要记录Authorization头、客户端Secret、完整上下文、业务Token、授权码、二维码或绑定码。错误报告只保留必要业务信息，公开讨论前还要去除员工身份和业务数据。
开放API常见错误
| HTTP或错误码 | 通常意味着什么 | 怎样处理 |
|---|---|---|
400 OPEN_API_REQUEST_INVALID |
请求字段或消息形状不支持 | 仅保留model、单条字符串user消息和同步入口可选stream；异步完全删除stream字段 |
400 MODEL_ROUTE_INPUT_INVALID |
显式模型目录ID格式错误 | 使用hive-agent或管理员确认的蜂巢目录ID，不填上游模型名称 |
MODEL_SELECTION_UNAVAILABLE |
模型未向Key绑定引擎开放或已不可用 | 核对当前模型目录与引擎，不自动换员工或扩大权限 |
400 OPEN_API_IDEMPOTENCY_KEY_INVALID |
标识格式不符 | 8—128字符，以字母数字开头，其余只用字母数字及._:- |
401 OPEN_API_UNAUTHORIZED |
Key无效、撤销或绑定员工不可用 | 停止重复调用，检查后端配置与当前员工状态 |
409 CLIENT_COMMAND_ID_CONFLICT |
同一标识用于不同输入 | 找出原业务操作；不能把改写请求当作原请求重试 |
429 AGENT_RUN_QUEUE_LIMIT_EXCEEDED |
员工待处理任务达到上限 | 降低并发、退避后使用原幂等标识重试，不绕过为另一员工 |
502 OPEN_API_RUN_FAILED |
执行失败 | 按任务记录核对模型、Skill、工具与业务错误，再决定是否修正后新建任务 |
409 OPEN_API_RUN_CANCELED |
同步执行被取消 | 核对已完成部分与业务结果，不自动当成从未执行 |
504 OPEN_API_TIMEOUT |
同步任务达到总时限，正在停止 | 检查任务和外部业务状态；不能承诺文件与业务修改已回滚 |
504 OPEN_API_REQUEST_TIMEOUT |
异步接口HTTP等待结束 | 任务可能仍存在；同标识重试提交或继续查询 |
404 OPEN_API_RUN_NOT_FOUND |
任务不存在、已删除或不属于原Key | 核对任务ID及创建Key；另一枚同员工Key也无权查询 |
409 OPEN_API_REQUEST_INVALIDATED_BY_RESTORE |
员工资产恢复使旧请求失效 | 先核对外部业务结果；不要自动换标识重新执行 |
这些是接入重点，服务仍可能返回其它明确错误。程序以error.code判断，不依赖中文提示文本的逐字匹配。
流已经开始，为什么仍然失败
SSE首先返回200，之后仍可能发送error块。只有收到成功完成块及[DONE]，才能认定成功流正常结束；没有完成就EOF时需要核对任务。
客户端按SSE空行边界解析事件，支持一次网络读取包含多条事件、单条事件跨多次读取，以及冒号开头的心跳注释。正文、原生思考和工具快照分别处理，不把工具活动追加成回答正文，也不自行执行这些工具。
同步连接断开会请求取消；异步断开不取消。需要可靠追踪长任务时使用异步入口，不要让短客户端超时不断创建新任务。
身份通过了，业务为什么仍然拒绝
- 核对网关是否检查
active、可信iss、自己的aud=system_id及exp，并以iss/sub找到业务用户。 ACCOUNT_LINK_REQUIRED表示业务系统还没有账号关联，引导用户从登记的“管理业务账号”入口处理。BUSINESS_PERMISSION_DENIED表示业务权限不足，联系业务系统管理员，不要求用户重新输入蜂巢密码。- Token过期时重新取得上下文，不退回旧密码、旧Token或匿名身份。写请求先确认上次实际结果，再决定重试。
OIDC access token、ID Token、开放API Key与业务Token用途不同。在线查询401检查业务后端客户端配置；429、503、超时和无效响应都拒绝受保护业务，不缓存旧的成功结果放行。
面板白屏、资源缺失或跨域失败
- 图片或脚本404：核对ZIP内路径、大小写和相对引用；
/images/...会请求站点根目录。缺文件不由蜂巢自动补齐。 window.hivePanel不可用：确认从员工工作台打开，而不是单独打开HTML；管理端预览不提供员工上下文。- 上下文失败：核对当前员工、面板资源、适用系统和系统资格；检查是否仍读旧的apiBaseUrl或requestHeaders字段。
access_token为null：检查目标系统客户端是否启用。公共属性可读不代表身份已经配置。- 浏览器只报网络失败：检查实际OPTIONS预检、
Origin:null和Authorization允许头；错误响应同样需要跨域头。 - 预览已打开但查询失败：读取页面错误和业务结果。预览也可能执行真实操作，不能通过反复点击写按钮排障。
详细示例见业务面板。
MCP或Skill没有出现在对话中
先核对当前业务范围，再检查独立资源分配、相关系统资格及员工本人启停。安装和授予业务权限不是同一件事。
MCP要使用Streamable HTTP；旧式HTTP+SSE服务不支持。连接测试只做初始化与发现，不证明业务调用；蜂巢身份模式要在获授权员工任务中验证。目录中的最近测试记录也不是实时健康。配置认证、范围或个人启停变化可能中断任务，不能在排查中反复切换当作无影响刷新。
个人Skill默认草稿，必须资料完整、本人确认启用、解析正常且范围匹配。市场安装要检查完整性和过渡状态；“我安装了”不一定代表当前可以使用。不要直接改受管理安装目录来修复，使用页面的核对修复或显式复制为个人Skill。
最后核对业务结果
任务显示完成后，仍要确认设备或记录范围、时间口径、数量与输出文件是否正确。任务失败或取消也可能留下已完成部分。不要因为界面停止更新就认定后端停止，更不能把取消、Key撤销或删除页面视为业务回滚。