Ошибки

Lovely Router использует стандартные HTTP-коды статуса. 2xx означает успех, 4xx — запрос нужно изменить (или пополнить баланс аккаунта), а 5xx или 429 — временную проблему, при которой стоит повторить запрос. Тело объясняет причину в формате вызванного вами API, поэтому официальные SDK выбрасывают привычные исключения.

Коды статуса#

Любые другие 5xx обрабатывайте как 502. Ошибки запросов, отклонённых до обращения к модели (400 для невалидного JSON, 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 уже отправлен, поэтому ошибки приходят в виде события внутри потока. Сбои до первого токена повторяются на другом канале, так что обычно поток либо завершается успешно, либо сразу падает с обычной HTTP-ошибкой.

Если модель перестаёт присылать данные посреди потока на 3 минуты, Lovely Router завершает поток событием ошибки в формате этого потока:

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

Ошибка, о которой канал сообщает внутри идущего потока, заменяется обобщённым событием в том же формате (для Responses API — событием error вида {"type": "error", "code": "server_error", "message": "…"}), так что исходная формулировка канала до вас не доходит. Занятый или перегруженный канал превращается в overloaded_error у Anthropic, rate_limit_exceeded у OpenAI или RESOURCE_EXHAUSTED у Gemini с сообщением 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, прежде чем начинать новый. См. Повторы и идемпотентность.

Официальные SDK OpenAI и Anthropic уже дважды повторяют 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.