黑洞智能体
黑洞智能体BLACK HOLE AGENTS

BLACK HOLE / DEVELOPER TOOLS

AI API 错误排查

先确认请求发到了哪里，再按状态码检查。这里提供定位顺序，具体原因仍以你的脱敏响应与服务日志为准。

400请求格式或参数不匹配

请求已到达接口，但正文、参数或所选模型不符合该接口要求。具体原因以响应正文为准。

  1. 先使用一条短文本和目录中的准确模型 ID；移除可选参数，再逐个加回。
  2. 区分聊天、图片生成、图片编辑和向量接口。支持文本不意味着支持图片或工具。
  3. 检查 JSON 是否有效、messages 是否为数组，以及 Content-Type 是否符合文档。

401身份认证未通过

服务器未接受本次请求携带的认证信息。密钥、认证头或接入服务不一致都需要检查。

  1. 确认使用黑洞账户的 API Key，并以 Authorization: Bearer 方式发送；登录浏览器的会话不是 API Key。
  2. 检查环境变量是否为空、是否多复制空格或换行，以及旧密钥是否已撤销。
  3. 先核对 Base URL。不要把其他厂商的密钥发送到黑洞地址，也不要把黑洞密钥发送到不认识的地址。

403请求被拒绝

服务器拒绝访问；权限、账户状态、路由或上游限制都可能有关，不能仅凭 403 判断是哪一项。

  1. 核对默认地址 https://blackholeagent.cn/v1，以及 API Key 所属账户和所选模型权限。
  2. 保留脱敏响应正文与发生时间。若短请求也失败，带上请求 ID 联系支持。
  3. 不要连续重试相同的被拒绝请求；先处理认证、权限或服务端明确给出的原因。

404地址或资源不存在

调用的路径或资源没有找到。模型不存在与 URL 拼错需要结合响应正文区分。

  1. Base URL 使用 https://blackholeagent.cn/v1；完整聊天地址是 /v1/chat/completions，避免出现 /v1/v1。
  2. 从目录复制模型 ID，保留日期后缀和连字符，不使用页面显示名称代替。
  3. 若经过本地网关，分别检查本地路由与其配置的远程地址。

429请求受到频率或额度限制

服务正在限制请求。频率、并发和额度可能使用不同限制，应读取具体错误与响应头。

  1. 若响应给出 Retry-After，按它等待；降低并发并采用带抖动的退避，避免同时重发。
  2. 核对账户额度和模型限制。额度不足时等待并不能解决问题。
  3. 重试前确认请求是否已执行或已计费，尤其是会写文件或执行工具的任务。

5xx网关、上游或服务端异常

500、502、503 和 504 都需要结合请求经过的服务定位。出现 127.0.0.1 时，错误可能由本机网关包装返回，不足以证明远程模型服务故障。

  1. 保存发生时间、完整状态码、脱敏正文和请求 ID；查看模型状态记录，再尝试一条独立的短请求。
  2. 区分任务总耗时、网络等待和上游响应中断。长任务中断后，先确认已有输出和工具执行结果再继续。
  3. 不要仅通过换域名或无限重试掩盖问题。重复出现时提供脱敏证据，分别检查客户端、本地网关与服务端。

整理一份可定位的问题记录

记录时间与时区、客户端版本、模型 ID、请求路径、状态码、请求 ID，以及脱敏后的错误正文。不要发送 API Key、Authorization 头、Cookie、真实资料或包含私人内容的完整请求。