Skip to main content
DeerAPI 的错误排查，最容易出问题的不是“错误码记不住”，而是 Base URL 打错、Token 配置错、把站点 HTML 当成 API 响应。这页是 DeerAPI 当前的权威错误码排障页，优先写客户端可直接验证的现象。
本页基于 DeerAPI 当前线上接口的最小化实测整理。已直接验证：400、401、路径/Base URL 错误。未在有边界测试中复现：413、429、500、503 等状态，因此这些部分只保留保守建议，不写死成单一原因。

​
快速判断

状态通常意味着什么是否建议立即重试第一检查项
400请求体在进入模型前就校验失败否检查 model、messages、JSON 结构与字段类型
401Token 缺失、格式不对或无效否检查 Authorization: Bearer <DEERAPI_KEY>
403请求被拦截，或当前请求不被允许通常否先排查 WAF、URL、Token 状态
路径错误Base URL 或 endpoint 写错，可能直接返回 HTML 页面而不是 JSON 错误否确认使用 https://api.deerapi.com/v1
429限流或临时拥塞是指数退避、降低突发并发
500、503平台或服务方暂时异常是记录 request id 后重试

​
当前错误响应外层结构

实测看到的 DeerAPI 错误响应外层通常是： 
{
  "error": {
    "code": "",
    "message": "...",
    "type": "rix_api_error"
  }
}
部分路由错误会返回 OpenAI 风格的 invalid_request_error，所以排障时不要只盯着 type，要同时看 HTTP 状态 + error.message。

​
400 Bad Request

线上实测：当请求体缺少 model 时，DeerAPI 返回： 
{
  "error": {
    "code": "",
    "message": "未指定模型名称，模型名称不能为空 (request id: ...)",
    "type": "rix_api_error"
  }
}
这类 400 一般说明请求在平台侧校验时就失败了，还没有正常进入模型调用。 常见原因：
  • 漏传 model
  • 漏传 messages
  • JSON 结构不合法
  • 字段类型不匹配
  • 复用了当前 endpoint 不接受的字段
建议：
  1. 先从最小可用请求开始调通。
  2. 只在请求成功后再逐步加上高级字段。
  3. 对照对应接口页的参数定义检查字段名。
最小可用请求示例： 
{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}

​
401 Invalid Token

线上实测：使用无效 Token 时，DeerAPI 返回： 
{
  "error": {
    "code": "",
    "message": "Invalid Token (request id: ...)",
    "type": "rix_api_error"
  }
}
优先检查：
  1. Header 是否是 Authorization: Bearer <DEERAPI_KEY>
  2. 应用是否还在读取旧的环境变量、旧配置文件或旧部署密钥
  3. Token 是否可用，是否被手动禁用
  4. Token 是否有额度或配置问题
关于额度、Key 与 Base URL 的常见误区，可结合 常见误区 一起排查。

​
403 Forbidden

我们没有在有边界测试中稳定复现 403，所以这里不把它写成单一原因。 按 Deer 当前帮助文档口径，403 更应该优先排查这些方向：
  • 请求 URL 或调用行为触发了 WAF 防护
  • Token 当前状态异常
  • 当前请求形态不被允许
建议排查顺序：
  1. 先用一个最简单的文本请求重试。
  2. 确认 Base URL、endpoint 和 header 都正确。
  3. 如果只有某个 URL 或某类请求会触发 403，优先怀疑 WAF 或平台侧拦截。
  4. 保留 request id 并联系支持。
不要直接照搬其他平台对 403 的解释。DeerAPI 当前更需要先排查 WAF、URL 与 Token 状态，而不是套用别的平台内部路由术语。

​
Base URL 或路径写错时，会发生什么

这是 DeerAPI 最容易误判的地方。 线上实测我们看到了两种不同表现：
  • 向 https://api.deerapi.com/chat/completions 发请求时，返回的是 HTTP 200 + HTML 页面，而不是 JSON 错误
  • 向 https://api.deerapi.com/v1/not-a-real-endpoint 发请求时，返回的是 HTTP 404 + JSON 错误
实测到的 404 示例： 
{
  "error": {
    "message": "Invalid URL (POST /v1/not-a-real-endpoint)",
    "type": "invalid_request_error",
    "code": ""
  }
}
这意味着 Base URL 或路径错误，可能会表现成：
  • SDK 解析 HTML 失败
  • 返回的不是 JSON
  • 真正的 404
  • 看起来“接口没反应”，但其实是请求打到了站点前端
请使用这个 base URL： 
https://api.deerapi.com/v1
排查路径问题时，建议：
  1. 先确认 Base URL 末尾包含 /v1
  2. 再确认 endpoint 路径是否与文档一致
  3. 调试阶段先不要自动跟随重定向或吞掉非 JSON 响应

​
413 Request Entity Too Large

我们没有在有边界测试中复现 413。即使发送了 8 MiB 的超大 JSON 请求，在当前测试里也没有直接返回 413。 所以如果你未来遇到 413，更安全的理解是：请求体太大，而不是简单地等同于“prompt 太长”。 优先怀疑：
  • 大型 base64 内容
  • 过大的图片、音频或其他内联输入
  • 单次 JSON 体积过大

​
429 Too Many Requests

我们没有在一组有边界的 24 个并发 GET /v1/models 探测里复现 429，所以不建议把 DeerAPI 的 429 写死成某一个固定阈值。 实务上，看到 429 时这样处理：
  1. 做指数退避并加入随机抖动
  2. 降低瞬时并发
  3. 观察 稳定性说明
  4. 需要代码示例时，参考 重试逻辑

​
500 与 503

我们没有在有边界测试中复现这两个状态，因此这里只保留保守建议。 可以把它们理解为：
  • 500：平台内部或服务方暂时异常
  • 503：当前路由或服务方暂时不可用
建议：
  1. 先退避重试
  2. 记录 request id、模型名、时间和 endpoint
  3. 若持续复现，再联系支持

​
联系支持前，先准备这些信息

  • HTTP method
  • endpoint 路径
  • model 名称
  • 脱敏后的 request body JSON 原文（这是绝大多数接口排障时最有用的一项）
  • 如果用了 query 参数，也请一并提供
  • 客户端拿到的原始响应体
  • 完整 HTTP 状态码
  • 原始 error.message
  • request id
  • 大致发生时间
  • 同一请求换一个 model 或换一个 Token 后是否仍复现
如果报错接口是文件上传类（图片编辑、音频上传、视频生成等），而不是普通 JSON 接口，请把完整提交载荷一起提供：
  • 随文件一起发送的字段名和对应文本值
  • 文件名、文件类型、文件大致大小
  • 文件是本地直传、URL 引用，还是 base64 内嵌
反馈效率最高的材料，不是截图，而是可复现的原始请求。绝大多数接口请直接提供脱敏后的 request body JSON；文件上传类接口请提供完整字段清单和文件元数据。