Ошибки — Errors API

Справочник ошибок API. Все ошибки возвращаются в едином формате.

Формат ошибки

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

HTTP-статус ответа совпадает с типом ошибки.

HTTP Status Codes

Коды ошибок

Ошибки валидации запроса (400)

Ошибки модели (400)

Ошибки аутентификации (401)

Ошибки баланса и доступа (402, 403)

Rate Limiting и лимиты (429)

Ошибки эндпоинтов

Ошибки видео

Retry-After Header

На ответах с кодом 429 Too Many Requests сервер может возвращать заголовок Retry-After с указанием количества секунд, через которое можно повторить запрос:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": {
    "message": "The service is receiving too many requests from you. Too many requests. Please try again in 30 seconds.",
    "code": "rate_limit_exceeded",
    "retry_after": 30
  }
}

Рекомендуется обрабатывать этот заголовок в клиентском коде:

import time
import requests

response = requests.post(
    "https://api.ru-openrouter.ru/v1/chat/completions",
    headers={"Authorization": "Bearer sk_..."},
    json={"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}
)

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", "5"))
    time.sleep(retry_after)
    # повторный запрос

Примеры ошибок

Ошибка валидации

{
  "error": {
    "code": "missing_model",
    "message": "Missing required parameter: model"
  }
}

Ошибка недопустимой роли

{
  "error": {
    "code": "invalid_message_role",
    "message": "Invalid 'role' value 'admin' at message index 0. Allowed: system, user, assistant, tool, function"
  }
}

Ошибка превышения контекста

{
  "error": {
    "code": "input_tokens_exceeded",
    "message": "Input tokens exceed model context limit. Model: 'openai/gpt-4o', Context length: 128000 tokens, Input tokens: 130000 (max allowed: 121600). Reduce message length."
  }
}

Ошибка провайдера

{
  "error": {
    "code": "openrouter_error",
    "message": "OpenRouter: Model 'openai/gpt-4o' is currently rate limited. Please try again later."
  }
}

Ошибка недостаточного баланса

{
  "error": {
    "code": "insufficient_balance",
    "message": "Недостаточно средств на балансе. Требуется: 10.50 ₽, Доступно: 5.00 ₽. Пожалуйста, пополните баланс или уменьшите параметр max_tokens / объём контекстного окна в запросе."
  }
}

Ошибка недоступного эндпоинта

{
  "error": {
    "code": "endpoint_not_found",
    "message": "Такого эндпоинта не существует, обратитесь к документации."
  }
}

Ошибка неподдерживаемого Media Type

{
  "error": {
    "code": "unsupported_media_type",
    "message": "Unsupported Media Type. Only application/json is allowed.",
    "received": "text/plain"
  }
}

Ошибка видео (модель требует изображение)

{
  "error": {
    "code": "video_generation_error",
    "message": "Эта модель работает только с изображением первого кадра. Загрузите изображение («Первый кадр») в настройках видео и попробуйте снова."
  }
}

Ошибки в streaming-режиме

При использовании stream: true ошибки обрабатываются по-разному в зависимости от момента возникновения.

Pre-Stream ошибки

Ошибки до отправки первого токена возвращаются как обычный HTTP-ответ с соответствующим статусом (4xx/5xx).

Debug mode (echo_upstream_body)

Прокси не фильтрует debug-чанки от OpenRouter. Если запрос содержит debug: { echo_upstream_body: true }, первый чанк SSE-потока будет содержать debug-данные с преобразованным телом запроса:

{
  "id": "gen-xxxxx",
  "provider": "Anthropic",
  "model": "anthropic/claude-haiku-4.5",
  "object": "chat.completion.chunk",
  "created": 1234567890,
  "choices": [],
  "debug": {
    "echo_upstream_body": {
      "system": [{ "type": "text", "text": "You are a helpful assistant." }],
      "messages": [{ "role": "user", "content": "Hello!" }],
      "model": "claude-haiku-4-5-20251001",
      "stream": true,
      "max_tokens": 64000
    }
  }
}

Важно: Debug mode работает только с stream: true.

Moderation и Guardrail

Если провайдер возвращает moderation/guardrail-ошибку, прокси ретранслирует её клиенту. Формат соответствует ответу провайдера:

{
  "error": {
    "code": 403,
    "message": "Request blocked: prompt injection patterns detected",
    "metadata": {
      "patterns": ["ignore all previous instructions"]
    }
  }
}

Медиа-типы

Поддерживаемые Content-Type для запросов: