错误

Lovely Router 使用标准的 HTTP 状态码。2xx 表示成功，4xx 表示请求需要修改（或者你的账户需要充值），5xx 或 429 表示值得重试的临时问题。响应体会以你所调用 API 的格式说明原因，因此官方 SDK 会抛出它们惯常的异常。

状态码#

其他任何 5xx 都按 502 处理。在到达模型之前就被拒绝的请求所产生的错误（无效 JSON 导致的 400、401、402、403、模型未知导致的 404，以及密钥限制导致的 429）永远不会计费。

模型端点的错误响应体#

模型端点以你所调用 API 的格式返回错误。下面每个标签页展示的是同一个 401。

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

每个状态码对应的错误 type（Anthropic 和 OpenAI）或 status（Gemini）：

在 Gemini 响应体中，error.code 始终等于 HTTP 状态码。请根据状态码而不是 status 字符串做分支判断。在读取请求之前产生的错误，例如端点未知或网关意外出错，同样使用你所调用端点的格式。

你可能看到的消息#

每个错误响应都带有 x-lovely-request-id 响应头，包括在到达模型之前就被拒绝的请求（密钥无效、余额为零、模型未知）。联系支持时请提供它。

工具和浏览器智能体的错误响应体#

/v1/tools 和 /v1/browser 的所有错误都使用同一种格式：一个机器可读的 type，加上一条写给人看的消息。

{"error": {"type": "insufficient_quota", "message": "Insufficient balance: this run can cost up to $0.3000 (100 results). Lower max_results or top up."}}

已经启动、随后失败的运行不算 HTTP 错误。返回的运行对象中，status 为 failed、timed_out 或 stopped，并带有一条 error 消息，你只为已返回的结果付费。参阅运行工具。

流式输出中的错误#

流一旦开始，状态码就已经是 200，因此错误会改为以流中的事件形式到达。首个 token 之前发生的失败会切换到其他渠道重试，所以通常你看到的流要么成功，要么以普通的 HTTP 错误失败。

如果模型在流的中途 3 分钟没有发送任何数据，Lovely Router 会以该流格式的错误事件结束这个流：

event: error
data: {"type": "error", "error": {"type": "api_error", "message": "Upstream stopped responding mid-stream"}}

渠道在运行中的流里报告的错误，会被替换为同一格式的通用错误事件（对于 Responses API，是类似 {"type": "error", "code": "server_error", "message": "…"} 的 error 事件），因此渠道自己的措辞不会传到你这里。渠道繁忙或过载时，会变为 Anthropic overloaded_error、OpenAI rate_limit_exceeded 或 Gemini RESOURCE_EXHAUSTED，消息为 Upstream capacity for this model is busy. Retry shortly.；其他情况都会变为 api_error（Gemini 为 UNAVAILABLE），消息为 The model provider returned an error. Please retry. 请从头重试请求；已经流式输出的内容会被计费。

重试失败的请求#

Lovely Router 在返回错误之前，已经会把失败的模型请求切换到其他渠道重试。对于它无法消化的情况，你这一侧也要重试：

• 重试 429、500、502、503、504 和网络错误。
• 等待 retry-after 响应头指定的秒数（如果有）。否则使用指数退避：1、2、4、8 秒，依此类推，最长 30 秒，再加上最多一秒的随机抖动，避免各个客户端同步重试。
• 大约尝试五次后停止，并把错误抛出。
• 不要重试 400、401、403、404、409、413 或 422，除非你修改了请求。402 只有在充值之后才重试。
• 不要盲目重试启动运行的请求。 如果启动工具运行或浏览器运行超时，请先检查 GET /v1/tools/runs，再决定是否启动新的运行。参阅重试与幂等性。

官方 OpenAI 和 Anthropic SDK 已经会以退避方式对 429 和 5xx 重试两次。要更改次数，请在创建客户端时传入 max_retries（Python）或 maxRetries（Node.js）。对于直接发起的 HTTP 调用，可以使用类似下面的辅助函数：

import os
import random
import time

import requests

RETRYABLE = {429, 500, 502, 503, 504}


def backoff(attempt, retry_after=None):
    if retry_after:
        return float(retry_after)
    return min(30, 2 ** (attempt - 1)) + random.random()


def post_with_retry(url, payload, max_attempts=5):
    headers = {"Authorization": f"Bearer {os.environ['LOVELY_API_KEY']}"}
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.post(url, json=payload, headers=headers, timeout=300)
        except (requests.ConnectionError, requests.Timeout):
            if attempt == max_attempts:
                raise
            time.sleep(backoff(attempt))
            continue
        if r.status_code in RETRYABLE and attempt < max_attempts:
            time.sleep(backoff(attempt, r.headers.get("retry-after")))
            continue
        if not r.ok:  # other 4xx, or still failing after the last attempt
            raise RuntimeError(f"{r.status_code}: {r.text[:500]}")
        return r.json()


reply = post_with_retry(
    "https://lovelyrouter.com/v1/chat/completions",
    {"model": "gpt-6.1-sol", "messages": [{"role": "user", "content": "Hello"}]},
)
print(reply["choices"][0]["message"]["content"])

所有错误格式（Anthropic、OpenAI、Gemini 以及 Lovely Router 自己的格式）都有一条写给人看的 error.message。记录日志时，请把它与状态码以及 x-lovely-request-id 响应头一起记录。