不要猜 API 错误，按响应证据分支排查。

直接答案

改代码前先采集响应

2026-08-24 的线上检查中，Primordial AI GET /v1/models 无鉴权请求返回 HTTP 401，并带有 x-oneapi-request-id；故意构造的 GET /v1/not-a-real-endpoint 返回 HTTP 404 和无效 URL 错误。这些结果确认了当前公开边界，但不代表每个错误都会使用相同 Body 或 Header。

请在可信服务端 Shell 运行。下面的命令会输出响应 Header 和响应 Body，但不会输出请求中的 Authorization Header：

if [ -z "${PRIMORDIAL_API_KEY:-}" ]; then
  echo "PRIMORDIAL_API_KEY 未设置" >&2
  exit 1
fi

curl --silent --show-error --include --max-time 30 \
  https://www.primoraihub.com/v1/models \
  -H "Authorization: Bearer $PRIMORDIAL_API_KEY"

HTTP 401：修复鉴权，不要重试

1. 确认环境变量存在，但不要输出变量值。
2. 确认 Header 准确写成 Authorization: Bearer YOUR_API_KEY。
3. 移除密钥中意外出现的引号、换行、前导空格和尾随空格。
4. 确认 Key 来自目标 Primordial AI 账户，并且仍处于启用状态。
5. 确认 API Base URL 是 https://www.primoraihub.com/v1，不是控制台页面或其他提供商域名。

创建、保存、无生成鉴权测试和安全轮换步骤请查看 API Key 快速入门。

HTTP 404 与模型不存在是两个排查分支

无效路由需要修正 URL 或 HTTP 方法；模型错误需要当前有效的模型标识。不要用随机模型名试错。

1. 检查响应状态和脱敏错误消息；无效 URL 消息指向接口路由。
2. 核对文档接口，包括 /v1 前缀和完整路径。
3. 带鉴权调用 GET /v1/models，从 data[].id 读取所有可用 ID。
4. 使用一个准确返回的 ID，并确认它支持应用调用的目标接口。
5. 删除旧缓存 ID；如果模型可用性变化，缩短缓存时间。

curl --silent --show-error \
  https://www.primoraihub.com/v1/models \
  -H "Authorization: Bearer $PRIMORDIAL_API_KEY" \
  | jq -r '.data[]?.id'

解析、缓存、空列表处理和接口检查请查看模型发现指南。

HTTP 429：区分瞬时限流和账户限制

不能把每个 429 都当成重试信号。先检查脱敏错误 Body 和响应 Header。若是临时请求速率或并发限流，有 Retry-After 时按该时间等待；没有时使用指数退避、抖动和较小次数上限。若错误明确指向额度、余额、消费或其他账户限制，必须先改变限制或账户状态。

• 增加重试前，先降低并发并删除重复请求。
• 不要盲目叠加应用重试；已安装 SDK 可能已经对合格错误自动重试。
• 设置总耗时和最大次数，防止故障演变成重试风暴。
• 在成本和延迟统计中，把原始请求与所有重试归为同一次业务操作。

OpenAI 官方错误指南区分了速率限制和余额、消费、用量限制，并建议在有 Retry-After 时遵守该 Header；官方 SDK 对符合条件的重试已经处理该 Header。这些内容描述 OpenAI API 和 SDK，不保证兼容网关使用相同错误码或 Header；排查 Primordial AI 时应以实际响应为依据。

HTTP 529、其他 5xx 与连接失败

HTTP 529：先读响应 Body，再决定动作

IANA HTTP 状态码注册表把 512–599 列为未分配，因此 HTTP 529 没有统一的已注册含义。Claude API 直连把 529 定义为 overloaded_error；这是提供商特定契约，不能证明每个兼容网关或上游都用 529 表达同一根因。

2026-09-09，Primordial AI 的隐私安全访问日志聚合观察到 6 次启发式 human-like 的 /v1 POST 返回 HTTP 529。访问日志没有响应 Body，也不能确定上游提供商、受影响人数、重试结果或客户端最终结果，因此根因仍未知。

1. 记录时间、模型 ID、请求 ID、状态，以及脱敏后的 error.type、error.code 和消息。
2. 若 Body 明确指向瞬时过载，有 Retry-After 时遵守该值，并使用次数很少、带抖动的指数退避。
3. 若 Body 指向模型、额度、余额、权限或账户问题，先修复该状态，不要重放同一请求。
4. 不能只凭状态码命名上游提供商或宣布服务故障。

其他 5xx、超时与连接失败

瞬时 5xx 可以短暂等待，再用指数退避和抖动重试。超时或连接失败还需要检查 DNS、代理或 VPN 路由、TLS 证书、防火墙、客户端超时配置，以及请求是在到达服务前还是到达后失败。

OpenAI 官方 Python 库提供 APIConnectionError、APITimeoutError、AuthenticationError、NotFoundError、RateLimitError 和 APIStatusError。下面的诊断示例只分类错误，不输出凭据：

import os
from openai import (
    OpenAI,
    APIConnectionError,
    APITimeoutError,
    APIStatusError,
    RateLimitError,
)

client = OpenAI(
    api_key=os.environ["PRIMORDIAL_API_KEY"],
    base_url="https://www.primoraihub.com/v1",
    timeout=30.0,
)

try:
    models = client.models.list()
    print(f"models={len(models.data)}")
except RateLimitError:
    print("rate_limited: 请检查响应细节和限制")
except APIStatusError as exc:
    print(f"api_status_error status={exc.status_code}")
except APITimeoutError:
    print("api_timeout_error")
except APIConnectionError:
    print("api_connection_error")

这些异常类型来自 OpenAI 官方 Python 错误参考。编写自动重试前，仍需根据已安装 SDK 版本和兼容网关实际响应进行验证。

日志要足以复现错误，但不能足以泄露凭据

记录时间、环境、HTTP 方法、路径、状态、耗时、第几次尝试、模型 ID、脱敏后的 error.type 或 error.code，以及响应中存在的 x-oneapi-request-id、x-request-id 等请求 ID。同时记录当时是否启用了代理或 VPN 路由。

不要记录 API Key、Authorization Header、Cookie、完整请求 Header，也不要在可能包含敏感数据时记录原始 Prompt 和响应。OpenAI 官方 API 概览说明了 OpenAI 的服务端请求 ID 和限流 Header；这些名称可以用于对照，但兼容网关不保证一定返回。

常见问题