星渊 API 指南

外观

报错怎么读 ​

先说一句：大部分报错不是你的问题。

接入新东西的时候遇到红字很正常，我们一条一条看。每条都告诉你「发生了什么」「怎么办」。

一张表先扫一眼 ​

HTTP常见含义该做什么
401Key 不对检查 Key 有没有复制全
403有 Key，但没权限 / 没额度看下面具体是哪一种
404路径不对多半是 /v1 重复或缺失
429请求太快等一会儿
500 / 502 / 503 / 504上游或线路的锅换分组或稍后重试

401 · Invalid token ​

json
{"error": {"message": "Invalid token"}}

这句的意思是「我不认识你这把钥匙」。常见原因：

  1. Key 复制时少了尾巴几位，或者多了空格
  2. Key 已经被删掉或禁用
  3. 令牌过期了（有些令牌设了有效期）

别急着新建 Key

先拿 curl 单独试一次。如果是复制问题，重新复制原 Key 就好，不用新建一把。

403 · 无权访问 X 分组 ​

json
{"error": {"message": "无权访问 Grok 分组"}}

这不是「你被封了」，是你这把令牌选的分组，账号等级里没有。

分组是有门槛的。比如 Grok、Pro-2、Kiro-3 这些，需要账号等级对得上才会出现。

怎么办：把令牌的「分组」改成不选（跟随账号），或者选一个你确定能用的分组。

403 · 用户额度不足 ​

json
{"error": {"message": "用户额度不足, 剩余额度: ¥0.000000",
  "code": "insufficient_user_quota"}}

余额不够了。这里显示的是账户余额，不是这把 Key 单独的余额。

充值后马上可用，不用重启任何东西。

403 · This token has no access to model ​

json
{"error": {"message": "This token has no access to model gpt-image-2.5"}}

这是令牌级别的模型限制——建令牌的时候勾了「限制模型」，而这个模型不在名单里。

怎么办：去令牌设置里把模型限制放开，或者换成名单里的模型。

这个和「分组不对」要分清

  • 「无权访问 X 分组」→ 账号等级的问题
  • 「no access to model X」→ 这一把令牌的限制问题

两句话长得像，但改的地方不一样。

404 · 路径不对 ​

绝大多数是 /v1 的问题：

text
https://api.syuan.org/v1/v1/chat/completions   ← 重复了
https://api.syuan.org/chat/completions          ← 少了

正确写法：https://api.syuan.org/v1/chat/completions

429 · 请求太快 ​

json
{"error": {"message": "您已达到请求数限制：1分钟内最多请求30次"}}

触发了频率限制。这不代表你被封号，只是短时间内请求太多。

怎么办：

  1. 等一会儿（通常 1 分钟就够）
  2. 请求失败后立刻重试，会让情况更糟——加个退避，比如失败后等 2 秒、4 秒、8 秒
  3. 如果是批量任务，把并发降到 2~3

顺手说一下

429 是保护性的。它限制的是频率，不是你的额度，也不会扣钱。被限流说明系统在正常工作。

503 · No available channel ​

json
{"error": {"message": "No available channel for model X under group CN",
  "code": "model_not_found"}}

虽然 code 写着 model_not_found，但更常见的原因是：

  1. 模型名打错了（最常见）
  2. 这个模型不在你选的分组里
  3. 该分组的线路临时都不可用

怎么办：先核对模型名拼写，再确认分组。都对了还是这样，换个分组试试。

503 / 504 · 上游超时 ​

json
{"error": {"message": "bad_response_status_code"}}

这是上游服务商那边的问题，不是渊站挂了你。通常几十秒后自己会恢复。

长文本、复杂推理、生图，本身就容易触发上游超时。

500 · 请求格式不对 ​

最常见的是 JSON 写错了，或者把 OpenAI 的请求体发给了 Claude 原生接口（或者反过来）。

怎么办：对着 API 调用 里的示例逐字比对。特别注意：

  • OpenAI 协议：messages
  • Claude 原生：messages + max_tokens（必填）+ anthropic-version 头
  • Gemini 原生：contents + parts

200 但内容不对 ​

有时候请求成功了，只是回答不理想。这通常和模型有关：

现象可能原因
回答很短、敷衍模型太小，或 max_tokens 设太小
答非所问system prompt 没生效，或模型不支持
中文夹英文换了别的模型，风格本来就这样

这种情况建议换一个更大一点的模型试一次，能快速判断是模型问题还是提示词问题。

还不行的话 ​

把这三样发给管理员，能省掉很多来回：

  1. request id（错误信息末尾那串）
  2. 你用的模型名和分组
  3. 完整的请求体（Key 记得去掉）

想自己先排查一遍 → 排障指南