ModelPort
ModelPort · 使用指南

AI API 调用错误排查：401、403、404、429 与 5xx｜ModelPort

ModelPort 编辑 · 更新于

先区分本地网关与上游，再决定修正鉴权、等待额度窗口或联系支持。记录端点、模型 ID、时间、是否流式、错误信息和请求标识（如有），不要提交完整密钥或敏感内容。

401：先查本地鉴权

确认使用完整的 Authorization: Bearer、x-api-key 或 x-goog-api-key 请求头，并检查密钥存在、未停用，关联用户仍可用。缺少或无效密钥、密钥被禁用、用户不可用会在本地鉴权阶段拦截；查询参数形式的密钥已被拒绝。

403：查访问范围与额度门槛

检查分组是否启用、用户是否获准使用该组及 IP 限制。普通按量密钥余额耗尽、密钥过期、订阅缺失或状态不合格通常是 403；自动路由切到下一组前也会重新检查该组授权。余额问题不能靠重复请求解决。

404：查模型、分组和端点

核对精确模型 ID、大小写和路径。分组白名单未列出的模型会在路由改写前拒绝；自动分组找不到登记该模型的已启用候选组，也会返回模型不存在类错误；当前平台不支持该端点同样可能是 404。客户端可选不代表当前密钥可调用。

429：区分本地与上游限流

本地 429 可能来自密钥额度、用户或分组 RPM、订阅日/周/月窗口、并发等待队列等，应查看账户、订阅和用量记录。上游 429 也会映射为限流响应，并在可用时保留 Retry-After；有该头就按它等待，没有就降低并发，避免紧密循环。

5xx：定位服务端还是上游

自动分组目录、计费服务等本地依赖故障会产生 5xx；上游 500、502、503、504 或过载也会转换成服务端错误。上游鉴权/访问拒绝不一定原样呈现为客户端 401/403，默认路径会记录上游状态并返回网关上游错误。看到 502/503，先保留时间和响应信息，不要立即重置密钥或反复充值。

不要盲目重试

自动分组只在响应未提交且故障被标记可重试时切换；普通 4xx、参数错误和已提交的流式响应不会自动重放。流式已经输出后，同一个请求不能重试到下一组；自行重发属于新请求，先核对请求标识与站内记录。

授权与切组见模型路由说明；费用疑问见计费说明。

可操作的最小诊断

先在启动 Codex 的同一终端确认密钥变量存在，但不要打印密钥值：

if [ -n "${MODELPORT_API_KEY:-}" ]; then
  curl -i --max-time 20 https://api.modelport.top/v1/models \
    -H "Authorization: Bearer $MODELPORT_API_KEY"
else
  echo "MODELPORT_API_KEY 未设置" >&2
fi
  1. 响应为 401 时，确认环境变量、env_key 名称和生效的用户级 ~/.codex/config.toml 一致；不要把密钥改放进项目文件。
  2. 响应为 403 时，检查密钥所属用户、分组授权、余额和 IP 限制；授权问题不会因重复请求或充值自动变成兼容。
  3. 若 /v1/models 端点本身返回 404，先核对 base_url 和路径；若目录请求成功但模型调用返回 404，再复制目录中的精确 ID（大小写也要一致）并检查当前分组能力。目录只是目录，不是调用保证。
  4. 响应为 429 时，降低并发并尊重 Retry-After；没有该响应头时也不要紧密循环重试，先查看额度和用量窗口。
  5. 响应为 5xx 或压缩阶段失败时，保存时间、模型、端点、状态码和请求标识，先做一次不含敏感数据的小请求；不要自行添加未经核对的模型/压缩参数，也不要公开日志中的密钥和提示词。

如果配置刚合并，完全退出并重新启动 Codex，让它重新读取用户级配置；仍失败时附上脱敏后的配置键名和诊断响应，保留原始密钥在本地。若使用命令行注入密钥可能进入 shell history，请改用交互式读取或系统 Secret 管理器。