故障排查

错误结构与你调用的协议保持一致。 /v1/chat/completions 和 /v1/responses 返回 OpenAI 风格的错误； /v1/messages 返回 Anthropic 风格的错误。三种协议的 HTTP 状态码完全一致。

错误响应格式

OpenAI 格式 (/v1/chat/completions, /v1/responses)

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Anthropic 格式 (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

401 · 认证失败 authentication_error

{"error":{"message":"missing API key in Authorization header or X-API-Key","type":"authentication_error"}}

原因

• 缺少 Authorization: Bearer 请求头(或 X-API-Key)——消息:missing API key in Authorization header or X-API-Key。
• 密钥与任何有效密钥都不匹配——消息:invalid API key。
• 密钥已过期——消息:API key expired。

解决

1. 发送 Authorization: Bearer sk-syn-…(或 X-API-Key: sk-syn-…)。
2. 在控制台确认密钥处于启用状态,且已完整复制。

400 · 无效请求 invalid_request

{"error":{"message":"model or models field is required","type":"invalid_request"}}

原因

• 缺少 model 字段,或 JSON 请求体为空或格式错误。

解决

1. 请提供 model 并使用格式正确的 JSON 请求体。参见 Chat Completions 参考。

403 · 配额耗尽 quota_exhausted

{"error":{"message":"API key quota exhausted","type":"quota_exhausted"}}

原因

• 密钥或工作区的预付余额已用完。

解决

1. 为工作区充值。注意:余额用尽时 Synthorai 返回 403 quota_exhausted,而非 429——因此指数退避无济于事;只有充值才能解除。

403 · 合规——不共享数据 compliance_blocked / compliance_no_data_share

{"error":{"type":"compliance_blocked","code":"compliance_no_data_share","message":"model 'MODEL' is unavailable: your workspace compliance setting disallows providers that retain/train on data"}}

原因

• 您的工作区启用了 no_provider_data_share,而所请求的模型仅由要求数据留存/共享的提供商提供(例如仅支持数据共享的 Bedrock 或 Vertex 模型)。

解决

1. 将请求路由到零留存模型,或在该工作负载可接受数据共享时关闭工作区合规开关。留存类别是每个模型的路由输入项——参见 30 天数据留存详解。

429 · 触发速率限制 rate_limit_exceeded

{"error":{"message":"rate limit exceeded: max 60 requests per minute","type":"rate_limit_exceeded"}}

原因

• 您超出了每分钟请求上限(RPM)。消息中会给出具体的限制值。

解决

1. 使用指数退避 + 抖动进行退避重试(见下方代码)。若需要持续的吞吐量,请申请更高的限制。

502 · 该模型没有可用通道 upstream_error

{"error":{"message":"no channels available for model \"MODEL\" in group \"default\"","type":"upstream_error"}}

原因

• 该模型 id 在您的工作区没有匹配的可路由通道——可能是拼写错误、已下架的模型,或您的套餐无法访问的模型。

解决

1. 对照实时模型列表核对准确的 id。如果某个模型最近已退役,请改用当前可用的模型。

BYOK:上游提供商错误

使用 bring-your-own-key 时,请求在您自己的提供商账户上运行(AWS Bedrock、Google Vertex AI 或 Anthropic API),因此 Synthorai 会原样透传提供商的原始错误——响应中带有 usage.is_byok: true。解决办法在该提供商的控制台或配置中,而非网关。最常见的是账户级的模型访问和数据共享设置:

上游提供商错误

这些错误由模型提供商透传,带有提供商自己的 HTTP 状态码和 type。只有 500 和 529 表示提供商侧的问题;应将它们(以及 429)视为瞬时性问题并重试,而 4xx 则反映请求本身。完整参考:Anthropic 的错误文档。

速率限制

速率限制按 API key 强制执行，以确保所有用户之间的公平使用。

默认限制

想根据真实的每 token 价格来规划 token 吞吐量?用 LLM API 成本计算器跑一遍您的工作负载。

处理 429 错误

import time
import openai

client = openai.OpenAI(base_url="https://synthorai.io/v1", api_key="YOUR_API_KEY")

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="gpt-5.4-mini",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except openai.RateLimitError as e:
        wait = 2 ** attempt  # exponential backoff
        print(f"Rate limited. Retrying in {wait}s...")
        time.sleep(wait)

async function withRetry(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxAttempts - 1) {
        const wait = Math.pow(2, attempt) * 1000;
        await new Promise(r => setTimeout(r, wait));
      } else throw err;
    }
  }
}

在某个模型上遇到 502 或过载?从模型价格对比中选一个备用模型——所有可路由模型及其每 token 价格尽在一张表中。