常见问题

按接入顺序排列——越靠前的越可能是你现在遇到的那个。 每条都指向对应的详细页面，需要深挖时点进去。

接入

Base URL 到底填什么？

https://www.apigoto.com/v1——这是绝大多数场景的答案。 唯一的例外是 Anthropic 官方 SDK 与 Claude Code，它们内部会自己拼 /v1/messages，所以要填不带 /v1 的 https://www.apigoto.com。填错的表现是 404 或路径里出现两个 v1。

我该用哪个端点？

取决于你手上的 SDK，与目标模型是哪家厂商的无关——协议不匹配时网关会转换。 拿不准就用 /v1/chat/completions。完整决策表见 协议与端点选择。

用官方 SDK 报 40001 api_key is required？

几乎可以肯定是 Anthropic SDK 用了 api_key=——那会发 x-api-key 头， 而网关只读 Authorization: Bearer。改成 auth_token= （Node 是 authToken），环境变量用 ANTHROPIC_AUTH_TOKEN。 同时记得清掉 ANTHROPIC_API_KEY，它通常优先级更高。

客户端的「获取模型列表」点了没反应？

那些客户端拉的是 OpenAI 的 GET /v1/models， 而 APIGOTO 的模型清单走平台接口 GET /api/v1/user/user/models，两者不通用。 手动把模型 ID 填进去即可，不影响对话。

鉴权与密钥

密钥明文丢了能找回吗？

不能。服务端只存哈希，明文只在创建时返回那一次。删掉重建即可—— 这是设计而非缺陷，见 鉴权与 API Key。

一个账号能建几把密钥？

可以建多把，建议按用途/环境分开（生产、测试、某个具体项目各一把）。 好处是出问题时可以精确停用一把而不影响其它业务，日志里也能分得清是谁在调。

密钥泄漏了怎么办？

立刻在控制台删除或禁用它，然后新建一把替换。 删除是即时生效的，之后用旧密钥的请求会返回 40101。 再去调用日志里核对泄漏期间有没有异常调用。

计费

新账号第一次调用就报 40202？

这是最常见的第一个错误：账号既没订阅，也没开「API 扣费访问」开关。 去用户中心打开开关即可。如果账号还没实名，错误提示里会追加实名引导—— 完成实名可以免费获得使用额度。

我充了钱，为什么报「积分不足」？

余额和积分是两个池子。调用扣的是积分，余额需要兑换成积分才能用。 去开启「自动兑换」（之后积分不够会自动从余额补），或手动兑换一次。 详见 计费、积分与订阅。

调用日志里有记录，消费记录里却是 0？

通常不是漏记，而是这几种情况之一：订阅额度覆盖（日志标记 subscription_covered）、BYOK 调用（费用在你自己的厂商账户上）、 或者折后金额不足 1 积分（直接免扣，不做四舍五入）。

请求失败了会扣费吗？

入口就被拒的（鉴权、限流、资格不足）不扣费——没到上游。 但已经打到上游、上游开始生成后才失败的（包括流式中途断开）， 已产生的 token 照扣，因为上游那边照收。 注意「参数越界」不算入口拒绝：max_tokens / 思考预算超过模型上限时网关不拦， 请求会真的发到上游，上游若在生成前就报错则不产生 token，也就不扣费。

怎么防止脚本写错跑量？

设「订阅外消费月度上限」（单位元，0 为不限），这是一道硬上界。 再配合密钥上的限制策略（并发/次数/Token 多档窗口）做第二层保险。

限流

42902 rpm limit exceeded，但我明明没那么高频？

因为策略层的请求次数、图片张数、视频数量、累计金额四个维度共用这一个错误码， message 是固定的英文文案，不代表真的是「每分钟请求数」。 以 Retry-After 和控制台的「使用情况」页面为准。

限流窗口什么时候重置？

不是整点重置。窗口以「该维度首次使用的时刻」为锚点向后推—— 比如「每小时 500 次」，首次调用在 10:17:32，那这一档就是 10:17:32 → 11:17:32。 所以不要靠看钟推算，读 Retry-After。

并发上限是 3，为什么只跑得动 2？

可能有槽位没释放（进程被 kill 等极端情况）。每个槽位存活超过 600 秒会自动剔除， 最多 10 分钟自愈。超过 10 分钟还这样，那就是真有请求在途——去查有没有卡住的长连接。

并发超了会排队等吗？

不会，直接返回 42901。需要排队的话得在客户端侧自己做， 比如用信号量控制并发数。

模型

50201 no available upstream for this model？

绝大多数情况是模型名写错了。请求里要写平台的 model_id， 不是上游厂商的原始模型名。去 /api/v1/user/user/models 核对拼写。

模型列表里有，调用却报 40203？

那是模型准入限制（需要某个认证等级或订阅套餐），不是模型不存在。 列表接口不做用户等级过滤，所以「看得到」不等于「调得动」。 具体差哪一档看 message，见 模型、准入与回退。

响应里的模型名和我请求的不一样？

触发了模型回退：原模型的所有上游都失败（包括被限流）后， 网关会改用你配置的回退模型再试一次。 对模型有强要求时，请校验响应里的模型名。不想要这个行为就别配回退模型。

能用 Anthropic 协议调 OpenAI 的模型吗？

可以。协议与模型是正交的——网关会做双向转换。 唯一的损耗是各厂商的专属扩展字段（安全设置粒度、缓存控制等）在目标协议里没有对应位置时会被丢弃。

流式

开了 stream: true，但还是一次性全出来？

九成是中间层缓冲了。curl 要加 -N； 自建 nginx 要 proxy_buffering off；CDN 上 SSE 路径要绕过缓存与压缩。 见 流式响应的「部署缓冲陷阱」。

怎么判断流式请求是成功还是断了？

看有没有收到终止事件，别只看 HTTP 状态码—— 一旦开始推流，状态码就锁死在 200 了。OpenAI 系看 data: [DONE]， Anthropic 看 message_stop，Responses 看 response.completed， Gemini 看最后一个片段有没有 finishReason。

用户点了「停止生成」，会退费吗？

不会。已经生成的 token 上游照收。 想控制成本应该靠 max_tokens，而不是靠中途掐断。

其它

请求体最大多少？

100 MiB，超出返回 41301。 纯文本对话远达不到；会触碰的基本只有 base64 图片和文件编辑类请求。

需要自己实现重试吗？

需要，但不用做得很复杂。网关内部已经替你在多条上游链路间重试过一轮， 错误传到你手上说明所有链路都试过了。客户端侧 3–4 次退避重试足够， 且只对 429（限流类）、504、部分 502 重试，别对 4xx 无脑重试。 参考实现见 错误处理与重试。

怎么区分是网关的错还是模型厂商的错？

看响应体里 error.type 是不是 "gateway_error"。 是就查错误码总表；不是就是上游原样透传，查对应厂商的文档。

数据会被用来训练吗？

APIGOTO 是转发网关，不用你的请求内容做模型训练。 但请求最终会到达上游厂商，其数据政策由该厂商决定。 对数据合规有严格要求时，建议用 BYOK——直接用你自己与厂商签的账户和条款。

还有问题？

先看错误码总表确认错误性质，再去控制台的调用日志找到那条具体记录。 反馈时带上时间、模型、错误码，排查会快很多。 控制台的「问题反馈」入口可以直接提交。