OpenNave 文档中心

外观

错误处理 ​

OpenNave API 调用可能遇到网关错误和上游提供商错误。本文说明不同协议的错误结构、可重试状态码及超时和重试策略。

错误分类 ​

网关错误 ​

网关错误在请求到达上游前发生，例如认证失败、频率限制或余额不足。代理端点会按请求协议返回相应格式。

OpenAI 格式（/v1/responses）：

json
{
  "error": {
    "message": "API key is invalid or has been revoked",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Anthropic 格式（/v1/messages）：

json
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "API key is invalid or has been revoked"
  }
}

Gemini 格式（/v1beta/models/*）：

json
{
  "error": {
    "code": 401,
    "message": "API key is invalid or has been revoked",
    "status": "UNAUTHENTICATED"
  }
}

管理 API（/web/v1/*）使用统一响应：

json
{
  "success": false,
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "msg": "API key is invalid or has been revoked"
  }
}

上游错误 ​

上游提供商返回错误时，OpenNave 会按原始协议格式透传。应用应按协议及 HTTP 状态码处理错误，不要假设所有响应都有相同 JSON 结构。

HTTP 状态码 ​

状态码含义建议处理
400请求格式或参数无效修正请求后再试。
401API Key 无效或缺失检查凭据。
402余额不足充值或调整账户余额。
403权限不足确认账户权限。
404端点或模型不存在检查 URL 和模型名称。
429请求过多使用指数退避重试。
500网关内部错误使用退避策略重试。
502上游不可达使用退避策略重试。
503服务临时过载使用退避策略重试。
504上游响应超时使用退避策略重试。

重试策略 ​

可重试错误 ​

只对 429、500、502、503 和 504 使用有限次数的指数退避与随机抖动。400、401、403、404 是客户端请求或权限问题，重试不会解决问题。

python
import random
import time
from openai import APIStatusError, OpenAI

client = OpenAI(
    base_url="https://api.opennave.top/v1",
    api_key="YOUR_OPENNAVE_API_KEY",
)

def make_request_with_retry(max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.responses.create(
                model="gpt-5.4",
                input="你好！",
            )
        except APIStatusError as error:
            if error.status_code not in (429, 500, 502, 503, 504):
                raise
            if attempt == max_retries - 1:
                raise
            delay = (2 ** attempt) + random.random()
            time.sleep(delay)

超时处理 ​

非流式请求通常可设置约 60 秒的超时；流式请求应设置至少 5 分钟的读取超时：

python
import httpx
from openai import OpenAI

client = OpenAI(
    base_url="https://api.opennave.top/v1",
    api_key="YOUR_OPENNAVE_API_KEY",
    timeout=httpx.Timeout(300.0, connect=10.0),
)

错误处理模式 ​

python
from openai import APIConnectionError, APIStatusError, APITimeoutError, OpenAI

client = OpenAI(
    base_url="https://api.opennave.top/v1",
    api_key="YOUR_OPENNAVE_API_KEY",
)

try:
    response = client.responses.create(model="gpt-5.4", input="你好！")
    print(response.output_text)
except APIConnectionError:
    print("无法连接到 API，请检查网络。")
except APITimeoutError:
    print("请求超时，请重试或增加超时时间。")
except APIStatusError as error:
    if error.status_code == 401:
        print("API Key 无效，请检查凭据。")
    elif error.status_code == 429:
        print("触发频率限制，请降低请求速率。")
    elif error.status_code >= 500:
        print(f"服务器错误（{error.status_code}），请稍后重试。")
    else:
        print(f"API 错误 {error.status_code}: {error.message}")

最佳实践 ​

  • 始终显式捕获错误，避免 API 异常导致应用崩溃。
  • 记录状态码、错误消息和请求 ID，但不要记录 API Key 或完整敏感请求内容。
  • 为持续出现的 5xx 错误设置熔断或更长时间的暂停策略。
  • 监控错误率，特别是 401、429 和 5xx 错误。

关联文档 ​