API VEGA

Индекс документации

Получите полный индекс документации по адресу: https://api.vega.chat/docs/llms.txt Используйте этот файл, чтобы узнать все доступные страницы перед дальнейшим исследованием.

Ошибки и отладка

MD версия

Ошибки API и отладка

typescript
export const HTTPStatus = { S100_Continue: 100, S101_Switching_Protocols: 101, S102_Processing: 102, S200_OK: 200, S201_Created: 201, S202_Accepted: 202, S203_Non_Authoritative_Information: 203, S204_No_Content: 204, S205_Reset_Content: 205, S206_Partial_Content: 206, S207_Multi_Status: 207, S208_Already_Reported: 208, S300_Multiple_Choices: 300, S301_Moved_Permanently: 301, S302_Found: 302, S303_See_Other: 303, S304_Not_Modified: 304, S305_Use_Proxy: 305, S307_Temporary_Redirect: 307, S308_Permanent_Redirect: 308, S400_Bad_Request: 400, S401_Unauthorized: 401, S402_Payment_Required: 402, S403_Forbidden: 403, S404_Not_Found: 404, S405_Method_Not_Allowed: 405, S406_Not_Acceptable: 406, S407_Proxy_Authentication_Required: 407, S408_Request_Timeout: 408, S409_Conflict: 409, S410_Gone: 410, S411_Length_Required: 411, S412_Precondition_Failed: 412, S413_Payload_Too_Large: 413, S414_URI_Too_Long: 414, S415_Unsupported_Media_Type: 415, S416_Range_Not_Satisfiable: 416, S417_Expectation_Failed: 417, S418_Im_a_teapot: 418, S421_Misdirected_Request: 421, S422_Unprocessable_Entity: 422, S423_Locked: 423, S424_Failed_Dependency: 424, S425_Too_Early: 425, S426_Upgrade_Required: 426, S428_Precondition_Required: 428, S429_Too_Many_Requests: 429, S431_Request_Header_Fields_Too_Large: 431, S451_Unavailable_For_Legal_Reasons: 451, S498_Invalid_Token: 498, S499_Client_Closed_Request: 499, S500_Internal_Server_Error: 500, S501_Not_Implemented: 501, S502_Bad_Gateway: 502, S503_Service_Unavailable: 503, S504_Gateway_Timeout: 504, S505_HTTP_Version_Not_Supported: 505, S506_Variant_Also_Negotiates: 506, S507_Insufficient_Storage: 507, S508_Loop_Detected: 508, S510_Not_Extended: 510, S511_Network_Authentication_Required: 511, S520_Web_Server_Returned_Unknown_Error: 520, S521_Web_Server_Is_Down: 521, S522_Connection_Timed_Out: 522, S523_Origin_Unreachable: 523, S524_A_Timeout_Occurred: 524, S525_SSL_Handshake_Failed: 525, S526_Invalid_SSL_Certificate: 526, S529_Overloaded: 529, S530_Origin_DNS_Error: 530 };

Для ошибок API VEGA возвращает JSON-ответ со следующей структурой:

typescript
type ErrorResponse = { error: { code: number; message: string; metadata?: Record<string, unknown>; }; };

HTTP‑ответ будет иметь тот же код статуса, что и error.code, образуя ошибку запроса, если:

  • Ваш исходный запрос некорректен
  • Ваш аккаунт VEGA или ключ VEGA исчерпал кредиты VEGA

Во всех остальных случаях возвращаемый HTTP‑статус будет <code>{HTTPStatus.S200_OK}</code>, а любые ошибки, возникшие во время генерации LLM, будут переданы в теле ответа или как событие SSE‑данных.

Пример кода для вывода ошибок в JavaScript:

typescript
const request = await fetch('https://openrouter.ai/...'); console.log(request.status); // Будет код ошибки, если модель не начала обработку запроса const response = await request.json(); console.error(response.error?.code); // Будет код ошибки console.error(response.error?.message);

Коды ошибок

  • {HTTPStatus.S400_Bad_Request}: Bad Request (некорректные или отсутствующие параметры, CORS)
  • {HTTPStatus.S401_Unauthorized}: Неверные учётные данные (сессия OAuth истекла, отключённый/некорректный ключ VEGA)
  • {HTTPStatus.S402_Payment_Required}: Ваш аккаунт или ключ VEGA имеет недостаточно кредитов VEGA. Добавьте больше кредитов VEGA и повторите запрос.
  • {HTTPStatus.S403_Forbidden}: Запрещено (недостаточно прав, блокировка guardrail, или флаг модерации)
  • {HTTPStatus.S408_Request_Timeout}: Время вашего запроса истекло
  • {HTTPStatus.S429_Too_Many_Requests}: Вы попали под ограничение скорости
  • {HTTPStatus.S502_Bad_Gateway}: Выбранная модель недоступна или мы получили некорректный ответ от неё
  • {HTTPStatus.S503_Service_Unavailable}: Нет доступного провайдера модели, удовлетворяющего вашим требованиям маршрутизации

Заголовок Retry-After

При ответах с кодами <code>{HTTPStatus.S429_Too_Many_Requests}</code> и <code>{HTTPStatus.S503_Service_Unavailable}</code> API VEGA может включать стандартный HTTP Retry-After заголовок, указывающий, сколько секунд ждать перед повторной попыткой.

http
HTTP/1.1 429 Too Many Requests Retry-After: 60

SDK OpenAI, Anthropic SDK, Vercel AI SDK и API VEGA SDK уже учитывают этот заголовок для обратного отката. Если вы используете fetch напрямую, соблюдайте его перед повторной попыткой:

typescript
const res = await fetch('https://openrouter.ai/api/v1/chat/completions', { ... }); if (res.status === 429 || res.status === 503) { const retryAfter = Number(res.headers.get('Retry-After')); if (Number.isFinite(retryAfter) && retryAfter > 0) { await new Promise((r) => setTimeout(r, retryAfter * 1000)); // повторить запрос } }

Ошибки модерации

Если ваш ввод был помечен, error.metadata будет содержать информацию о проблеме. Структура метаданных выглядит так:

typescript
type ModerationErrorMetadata = { reasons: string[]; // Почему ваш ввод был помечен flagged_input: string; // Текстовый сегмент, который был помечен, ограниченный 100 символами. Если помеченный ввод длиннее 100 символов, он будет усечён посередине и заменён на ... provider_name: string; // Название провайдера, запросившего модерацию model_slug: string; };

Ошибки guardrail

На эндпоинтах инференса (/chat/completions, /responses, /messages) запрос может быть заблокирован до того, как он достигнет провайдера — например, фильтром контента или детектором внедрения подсказки, настроенным через guardrails. Когда это происходит, ответ имеет статус 403 с сообщением, описывающим причину блокировки. Тело ответа в формате API VEGA ниже применяется к /chat/completions и /responses; на /messages блок возвращается как оболочка Anthropic permission_error (см. Anthropic Messages ниже), при этом openrouter_metadata всё ещё передаётся на верхнем уровне, если включён соответствующий флаг:

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

Когда вы включаете router metadata через заголовок X-OpenRouter-Experimental-Metadata: enabled, 403‑ответ также включает полный объект openrouter_metadata с контекстом маршрутизации и массивом pipeline, описывающим пройденные стадии guardrail:

json
{ "error": { "code": 403, "message": "Request blocked: prompt injection patterns detected", "metadata": { "patterns": ["ignore all previous instructions"] } }, "openrouter_metadata": { "requested": "openai/gpt-4o", "strategy": "direct", "region": "iad", "summary": "available=1", "attempt": 1, "is_byok": false, "endpoints": { "total": 1, "available": [ { "provider": "OpenAI", "model": "openai/gpt-4o", "selected": false } ] }, "pipeline": [ { "type": "guardrail", "name": "regex_pi_detection", "guardrail_id": "grd_abc123", "guardrail_scope": "api-key", "summary": "Blocked: prompt injection detected (1 pattern matched)", "data": { "action": "blocked", "detected": true, "engines": ["regex"], "patterns": ["ignore all previous instructions"] } } ] } }

Объект openrouter_metadata следует той же структуре, что и в успешных ответах — см. Pipeline Stages для полного описания типов стадий и полей.

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

API VEGA нормализует каждую ошибку upstream‑провайдера в стабильный типизированный словарь error_type, описанный в разделе Typed Error Codes. Те же значения error_type описывают, что пошло не так, независимо от того, приходит ли ошибка провайдера в теле не‑стримингового ответа или как событие SSE в середине потока. Нативные коды протокола (Anthropic error.type, Responses error.code) являются приближенными и могут различаться между форматами — error_type является полем, на которое следует опираться во всех случаях.

Для Chat Completions ошибка провайдера, прерывающая генерацию, содержит error_type внутри error.metadata:

json
{ "error": { "code": 429, "message": "Rate limit exceeded", "metadata": { "error_type": "rate_limit_exceeded", "provider_code": "rate_limited" } } }

То же значение передаётся в ошибках посередине потока и в скинах Anthropic и Responses — см. Skin-Specific Error Formats для точного расположения в каждом формате.

Маскирование и сырые детали провайдера

Когда запрос завершается с кодом 500, message заменяется на общее сообщение, а provider_code и openrouter_metadata опускаются, но error_type остаётся (server).

Для ошибок, не являющихся 500, оригинальный код ошибки провайдера отображается в error.metadata.provider_code, если он доступен. При включённом контексте маршрутизации (какой провайдер был выбран, попытки fallback и т.д.) информация передаётся в объекте openrouter_metadata при установке заголовка X-OpenRouter-Metadata — он имеет ту же структуру, что и в успешных ответах (только поля сводки маршрутизации; см. Pipeline Stages).

Когда контент не генерируется

Иногда модель может не сгенерировать никакого контента. Это обычно происходит, когда:

  • Модель прогревается после холодного старта
  • Система масштабируется для обработки большего количества запросов

Время прогрева обычно составляет от нескольких секунд до нескольких минут, в зависимости от модели и провайдера.

Если вы сталкиваетесь с постоянными проблемами отсутствия контента, рассмотрите возможность простого механизма повторных попыток или попробуйте другой провайдер или модель с более свежей активностью.

В некоторых случаях вы всё равно можете быть начислены за обработку подсказки upstream‑провайдером, даже если контент не был сгенерирован.

Форматы ошибок при стриминге

При использовании режима стриминга (stream: true) ошибки обрабатываются по‑разному в зависимости от того, когда они происходят:

Ошибки до начала стрима

Ошибки, возникшие до отправки любых токенов, следуют стандартному формату ошибок, описанному выше, с соответствующими HTTP‑кодами. На этом этапе HTTP‑ответ ещё не отправлен, поэтому API VEGA может:

  • Вернуть корректный HTTP‑код ошибки (4xx/5xx)
  • Тихо повторить запрос к другому провайдеру, если включён fallback routing
  • Применить проверки ограничения скорости или аутентификации до начала работы

Вы увидите такие ошибки при некорректных ключах VEGA, неверных запросах или когда все доступные эндпоинты провайдеров исчерпаны до начала стриминга.

Ошибки в середине стрима

Как только первый токен отправлен клиенту, статус 200 OK и заголовки уже зафиксированы — их нельзя изменить. Если провайдер падает в этот момент, API VEGA не может тихо переключиться на другого провайдера, потому что часть контента уже доставлена вашему приложению. Ошибка должна быть передана в‑полосе как событие SSE.

Типичные причины ошибок в середине стрима:

  • Отключение провайдера — upstream‑соединение прерывается после частичного вывода (проблема сети, сбой провайдера, таймаут балансировщика)
  • Таймаут провайдера — модель перестаёт отвечать посередине генерации, и срок чтения истекает
  • Превышение лимита токенов во время генерации — модель достигает max_tokens или заполняет контекстное окно
  • Фильтр контента вывода — система модерации помечает сгенерированный текст после того, как часть его уже была передана
  • Перегрузка провайдера — upstream возвращает ошибку ограничения скорости или ёмкости после начала стриминга

Если ошибка происходит до отправки любого токена — даже при запросе со стримингом — API VEGA всё ещё может тихо переключиться на резервный провайдер. Ошибки в середине стрима возникают только после того, как часть контента уже зафиксирована в вашем потоке, делая переключение невозможным.

Ошибки в середине стрима отправляются как Server‑Sent Events (SSE) с унифицированной структурой, включающей как детали ошибки, так и завершённый выбор:

typescript
type MidStreamError = { id: string; object: 'chat.completion.chunk'; created: number; model: string; provider: string; error: { code: number; // HTTP‑код статуса (например 400, 429, 502) message: string; metadata?: { error_type: string; // Типизированный код ошибки — см. таблицу ниже provider_code?: string; // Оригинальный код upstream‑провайдера (опущен в 500‑х) }; }; choices: [{ index: 0; delta: { content: '' }; finish_reason: 'error'; native_finish_reason?: string; }]; };

Пример данных SSE:

text
data: {"id":"gen-abc123","object":"chat.completion.chunk","created":1234567890,"model":"openai/gpt-4o","provider":"OpenAI","error":{"code":429,"message":"Rate limit exceeded","metadata":{"error_type":"rate_limit_exceeded"}},"choices":[{"index":0,"delta":{"content":""},"finish_reason":"error"}]}

Ключевые характеристики:

  • Ошибка появляется на верхнем уровне вместе со стандартными полями ответа
  • error.metadata.error_type содержит типизированный код, который можно программно обрабатывать — см. Typed Error Codes
  • В массиве choices присутствует finish_reason: "error" для корректного завершения потока
  • HTTP‑статус остаётся 200 OK, так как заголовки уже отправлены
  • Поток завершается после этого события
  • В ошибках класса 500 error.message заменяется на общее сообщение, а provider_code опускается, чтобы не раскрывать детали upstream‑провайдера

Типизированные коды ошибок

Когда ошибка провайдера достигает вашего приложения, API VEGA помечает её канонической строкой error_type — как в не‑стриминговом теле ответа, так и в событиях SSE посередине потока. Используйте это значение, а не только HTTP‑статус, для программного различения категорий ошибок. Оно стабильно во всех трёх API‑скинах, даже если нативный код протокола потерян.

Где error_type появляется, зависит от скина и пути:

  • Chat Completions: error.metadata.error_type — в ошибочном чанке посередине потока (см. Mid‑Stream Errors) и в не‑стриминговом ответе, когда ошибка провайдера прерывает генерацию.
  • Anthropic Messages: error.error_type в событии SSE error и в не‑стриминговом конверте ошибки.
  • Responses: error_type на верхнем уровне в не‑стриминговом JSON‑теле и в событии response.failed при стриминге.

Код HTTP, соответствующий каждому error_type, перечислен в таблицах ниже.

Ограничения токенов и длины

error_typeHTTP‑статусОписание
context_length_exceeded{HTTPStatus.S400_Bad_Request}Совокупное количество входных и выходных токенов превышает контекстное окно модели.
max_tokens_exceeded{HTTPStatus.S400_Bad_Request}Генерация остановлена, потому что достигнут max_tokens (или max_completion_tokens).
token_limit_exceeded{HTTPStatus.S400_Bad_Request}Превышен бюджет токенов, установленный API VEGA (например, ограничение по кредитам).
string_too_long{HTTPStatus.S400_Bad_Request}Одна строка в запросе (system prompt, пользовательское сообщение и т.д.) превышает ограничение провайдера по символам.

Аутентификация и авторизация

error_typeHTTP‑статусОписание
authentication{HTTPStatus.S401_Unauthorized}Ключ VEGA отсутствует, некорректен или отозван.
permission_denied{HTTPStatus.S403_Forbidden}Ключ действителен, но не имеет требуемых прав, либо запрос заблокирован guardrail.
payment_required{HTTPStatus.S402_Payment_Required}У аккаунта VEGA или ключа VEGA недостаточно кредитов VEGA. Добавьте кредиты VEGA и повторите.

Ограничения скорости и доступность

error_typeHTTP‑статусОписание
rate_limit_exceeded{HTTPStatus.S429_Too_Many_Requests}Достигнут лимит запросов или токенов. Уважайте заголовок Retry-After перед повтором.
provider_overloaded{HTTPStatus.S503_Service_Unavailable}В upstream‑провайдере временная перегрузка. Повторите запрос после небольшой задержки.
provider_unavailable{HTTPStatus.S502_Bad_Gateway}В upstream‑провайдере получен некорректный или пустой ответ. API VEGA может автоматически повторить запрос к другому провайдеру, если включён fallback routing.

Проверка запросов

error_typeHTTP‑статусОписание
invalid_request{HTTPStatus.S400_Bad_Request}Параметр запроса malformed или отсутствует.
invalid_prompt{HTTPStatus.S400_Bad_Request}Конкретное сообщение в массиве messages некорректно (например, неподдерживаемая роль, пустой контент).
not_found{HTTPStatus.S404_Not_Found}Запрашиваемый ресурс (модель, файл и т.д.) не существует.
precondition_failed{HTTPStatus.S412_Precondition_Failed}Заголовок предусловия (например, If-Match) не выполнен.
payload_too_large{HTTPStatus.S413_Payload_Too_Large}Тело запроса превышает максимально допустимый размер.
unprocessable{HTTPStatus.S422_Unprocessable_Entity}Запрос синтаксически корректен, но семантически не может быть обработан.

Политика контента

error_typeHTTP‑статусОписание
content_policy_violation{HTTPStatus.S400_Bad_Request}Ввод или вывод был помечен фильтром контента (на уровне провайдера или API VEGA).
refusal{HTTPStatus.S400_Bad_Request}Модель явно отказалась выполнять запрос (например, из соображений безопасности).

Ошибки изображений

error_typeHTTP‑статусОписание
invalid_image{HTTPStatus.S400_Bad_Request}Изображение в запросе повреждено или нечитаемо.
image_too_large{HTTPStatus.S400_Bad_Request}Изображение превышает максимальный размер файла или пиксельные размеры, установленные провайдером.
image_too_small{HTTPStatus.S400_Bad_Request}Изображение меньше минимальных пиксельных размеров, требуемых провайдером.
unsupported_image_format{HTTPStatus.S400_Bad_Request}Формат изображения не поддерживается провайдером.
image_not_found{HTTPStatus.S404_Not_Found}URL изображения или ID файла не удалось разрешить.
image_download_failed{HTTPStatus.S400_Bad_Request}API VEGA не смог загрузить изображение по указанному URL (ошибка DNS, таймаут, ответ не 200 и т.д.).

Общие

error_typeHTTP‑статусОписание
server{HTTPStatus.S500_Internal_Server_Error}Неожиданная внутренняя ошибка. Сообщение upstream‑провайдера замаскировано в этом типе.
timeout{HTTPStatus.S504_Gateway_Timeout}Провайдер не ответил в отведённое время.
unmapped{HTTPStatus.S500_Internal_Server_Error}Ошибка upstream‑провайдера, не попадающая в известные категории. error.metadata.provider_code может содержать оригинальный код.

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

Когда запрошенная модель не может быть обслужена — она не существует, устарела, не имеет маршрутизируемых эндпоинтов согласно вашим предпочтениям, или все её провайдеры находятся в состоянии полной загрузки — ответ об ошибке содержит дополнительный объект error.availability. Он добавочный: error_type, http_status и message сохраняют свои значения, поэтому существующая обработка ошибок продолжает работать. Используйте availability.code — а не HTTP‑статус или текст сообщения — для программного различения условий доступности.

Тот же объект availability включается в чанки ошибок при стриминге для всех трёх API‑скинов (Chat Completions, Responses, Anthropic Messages).

Коды доступности

Каждое событие недоступности модели сопоставляется ровно одному коду. Коды стабильны навсегда; в будущем могут появиться новые, поэтому неизвестный код следует обрабатывать как retryable.

availability.codeHTTP‑статусerror_typeRetryableЗначениеРекомендуемое действие клиента
model_not_found{HTTPStatus.S400_Bad_Request}invalid_requestНетИдентификатор модели неизвестен или некорректен.Не повторять. Проверьте опечатки в slug или используйте предложения fallback_models, если они присутствуют.
wrong_endpoint{HTTPStatus.S400_Bad_Request}invalid_requestНетМодель существует, но вызвана на неверном эндпоинте (например, embedding‑модель на /chat/completions).Повторить запрос на эндпоинте, указанном в constraint.detail.
no_endpoints{HTTPStatus.S404_Not_Found}not_foundНетМодель существует, но не имеет маршрутизируемых эндпоинтов (не настроены, отключены/скрыты, или удалены вашими предпочтениями провайдеров).Не повторять идентичный запрос. Ослабьте предпочтения маршрутизации провайдера или выберите другую модель.
model_deprecated{HTTPStatus.S404_Not_Found}not_foundНетМодель устарела или удалена (sunset‑модели, завершённые stealth‑альфы).Перейдите к преемнику в fallback_models; см. docs_url для уведомления об устаревании.
model_unavailable_upstream{HTTPStatus.S404_Not_Found}not_foundНетКаждый эндпоинт модели возвращает 404 upstream — провайдер удалил её.Не повторять запрос. Выберите другую модель (fallback_models, если они есть).
capacity_exhausted{HTTPStatus.S429_Too_Many_Requests}rate_limit_exceededДаВсе провайдеры модели находятся в состоянии полной загрузки (все попытки вернули 429).Повторить запрос после retry_after секунд (также передаётся в заголовке Retry-After), либо использовать fallback_models.
temporarily_unavailable{HTTPStatus.S503_Service_Unavailable}provider_overloadedДаВсе попытки завершились временными 5xx‑ответами upstream или таймаутами.Повторить с экспоненциальным откатом, учитывая retry_after, если он присутствует; рассмотреть fallback_models для чувствительных к задержкам путей.
region_restricted{HTTPStatus.S403_Forbidden}permission_deniedНетМодель ограничена географически и недоступна в вашем регионе.Не повторять из того же региона. Настройте предпочтения провайдера или обслуживайте трафик из разрешённого региона.
privacy_restricted{HTTPStatus.S404_Not_Found}not_foundНетВаши предпочтения политики данных (ZDR, отказ от обучения, публикация бесплатных моделей) исключили все эндпоинты.Снимите ограничение, указанное в excluded_by (например, в privacy settings), либо выберите другую модель.
constraint_filtered{HTTPStatus.S404_Not_Found}not_foundНетОграничение маршрутизации — максимальная цена, длина контекста, require_parameters, квантизация, регион данных — исключили все эндпоинты.Ослабьте ограничение, указанное в constraint.field / excluded_by, и повторите запрос.
free_variant_ended{HTTPStatus.S404_Not_Found}not_foundНетПромо‑вариант :free завершён; остались только платные эндпоинты.Перейдите к платному slug в fallback_models (применяется обычное ценообразование) или выберите другую модель.

no_endpoints и model_unavailable_upstream сегодня не являются повторяемыми, но роутер может пометить отдельные случаи как retryable: true, если подлежащая причина временная. Всегда проверяйте availability.retryable, а не только код.

Объект availability

typescript
type AvailabilityError = { code: string; // один из кодов выше — машинно‑читаемый дискриминатор retryable: boolean; // может ли идентичный повтор завершиться успешно? retry_after?: number | null; // секунды ожидания перед повтором, если известны (пути 429/503) requested_models: string[]; // исходные slug‑модели, которые вы отправили affected_providers?: string[] | null; // провайдеры, эндпоинты которых были попытаны или исключены excluded_by?: string[]; // фильтры маршрутизации, которые удалили последние эндпоинты fallback_models?: string[]; // предложенные альтернативные slug‑модели; могут быть пустыми или отсутствовать constraint?: { // присутствует при `constraint_filtered` и `wrong_endpoint` field: string; // например "max_price" detail: string; // человекочитаемое объяснение }; docs_url: string; // якорь для этого кода на текущей странице };

code, retryable, requested_models и docs_url всегда присутствуют в ошибке доступности. Другие поля опускаются (не сериализуются как пустые строки), если не применимы. Значения excluded_by берутся из фиксированного словаря: geo, data_region, data_policy:zdr, data_policy:training, max_price, context_length, require_parameters, quantization, allowed_providers.

Для отладки error.metadata.previous_errors содержит историю попыток провайдера в компактной, стабильной форме — { "provider": "...", "code": "...", "status": 429 } — и никогда не включает сырые тела ошибок upstream‑провайдера.

Повтор с retry_after

Для capacity_exhausted и temporarily_unavailable availability.retry_after дублирует заголовок Retry-After в теле и заполняется, когда любой из попытанных эндпоинтов предоставил подсказку о повторе (минимум среди попыток). Оба значения выражаются в секундах:

typescript
const res = await fetch('https://openrouter.ai/api/v1/chat/completions', { ... }); const body = await res.json(); const availability = body.error?.availability; if (availability?.retryable) { const waitSeconds = availability.retry_after ?? Number(res.headers.get('Retry-After')) || 2 ** attempt; // экспоненциальный откат, если подсказка отсутствует await new Promise((r) => setTimeout(r, waitSeconds * 1000)); // повторить идентичный запрос }

SDK OpenAI, Anthropic, Vercel AI и API VEGA SDK уже учитывают заголовок Retry-After; availability.retry_after предоставляет тот же сигнал клиентам, которые читают тело вместо заголовков.

Использование предложений fallback_models

fallback_models содержит альтернативные slug‑модели, которые роутер может предложить дешево — платный вариант после окончания :free‑промо, преемник устаревшей модели или альтернативы той же семьи. Поле опускается, если предложений нет, и никогда не задерживает ответ об ошибке.

Предложения — лишь подсказки, а не гарантии: fallback‑модель может отличаться по цене, контекстному окну или возможностям, и может быть недоступна при ваших предпочтениях маршрутизации. Проверьте slug относительно ваших требований (или покажите пользователю) перед автоматическим переключением.

Примеры полезных нагрузок ошибок доступности

Все провайдеры на пределе — capacity_exhausted (повторяемо):

json
{ "error": { "message": "All providers for anthropic/claude-sonnet-4.5 are at capacity. Retry after 40 seconds.", "error_type": "rate_limit_exceeded", "http_status": 429, "availability": { "code": "capacity_exhausted", "retryable": true, "retry_after": 40, "requested_models": ["anthropic/claude-sonnet-4.5"], "affected_providers": ["anthropic", "amazon-bedrock", "google-vertex"], "fallback_models": ["anthropic/claude-haiku-4.5"], "docs_url": "https://api.vega.chat/docs/errors#capacity_exhausted" }, "metadata": { "previous_errors": [ { "provider": "anthropic", "code": "capacity_exhausted", "status": 429 }, { "provider": "amazon-bedrock", "code": "capacity_exhausted", "status": 429 } ] } } }

Устаревшая stealth‑модель — model_deprecated:

json
{ "error": { "message": "Quasar Alpha was a stealth model, revealed on April 14th as an early testing version of GPT-4.1.", "error_type": "not_found", "http_status": 404, "availability": { "code": "model_deprecated", "retryable": false, "requested_models": ["openrouter/quasar-alpha"], "fallback_models": ["openai/gpt-4.1"], "docs_url": "https://api.vega.chat/docs/errors#model_deprecated" } } }

Ограничения конфиденциальности исключили все эндпоинты — privacy_restricted:

json
{ "error": { "message": "No endpoints for openai/gpt-5.2 match your data policy (zero data retention). Adjust at https://api.vega.chat/settings/privacy.", "error_type": "not_found", "http_status": 404, "availability": { "code": "privacy_restricted", "retryable": false, "requested_models": ["openai/gpt-5.2"], "affected_providers": ["openai", "azure"], "excluded_by": ["data_policy:zdr"], "docs_url": "https://api.vega.chat/docs/errors#privacy_restricted" } } }

Неизвестный идентификатор модели — model_not_found:

json
{ "error": { "message": "acme/fake-1.0 is not a valid model ID", "error_type": "invalid_request", "http_status": 400, "availability": { "code": "model_not_found", "retryable": false, "requested_models": ["acme/fake-1.0"], "docs_url": "https://api.vega.chat/docs/errors#model_not_found" } } }

Форматы ошибок, специфичные для скинов

API VEGA предоставляет три API‑скина. Каждый переводит одинаковые внутренние типы ошибок провайдера в свой собственный формат, как для не‑стриминговых ответов, так и для ошибок в потоке. Во всех случаях error_type остаётся стабильным полем; место его расположения различается в зависимости от скина.

Chat Completions (/api/v1/chat/completions)

Ошибки посередине потока появляются как chat.completion.chunk с объектом error верхнего уровня (см. выше). Поле error.metadata.error_type несёт типизированный код.

Для не‑стриминговых запросов, где происходит ошибка провайдера, ошибка встраивается в окончательный ответ вместе с любой частичной выдачей:

json
{ "choices": [{ "message": { "role": "assistant", "content": "partial output..." }, "finish_reason": "error", "error": { "code": 502, "message": "Provider disconnected mid-stream", "metadata": { "error_type": "provider_unavailable" } } }] }

Responses API (/api/v1/responses)

Responses API отображает внутренние типы ошибок в набор кодов ошибок OpenAI Responses. Отображение более узкое — многие внутренние типы сводятся к server_error, поэтому точная причина сохраняется в поле error_type верхнего уровня, вне нативного объекта error:

Внутренний error_typeResponses API code
rate_limit_exceededrate_limit_exceeded
context_length_exceeded, invalid_requestinvalid_prompt
content_policy_violationimage_content_policy_violation
authentication, provider_overloaded, provider_unavailable, timeout, serverserver_error
Все остальные (включая invalid_prompt)server_error

Оба — потоковое завершающее событие и не‑стриминговый JSON‑тело — содержат канонический error_type на верхнем уровне объекта ответа. Например, ошибка аутентификации сводится к нативному коду server_error, но сохраняет error_type: "authentication":

json
{ "id": "resp_abc123", "status": "failed", "error": { "code": "server_error", "message": "Invalid credentials" }, "error_type": "authentication" }

Ошибки в потоке передаются как один из трёх SSE‑событий, каждый оборачивает тот же объект ответа:

  1. response.failed — завершающее событие, когда ответ не может быть завершён:

    json
    { "type": "response.failed", "response": { "id": "resp_abc123", "status": "failed", "error": { "code": "server_error", "message": "Internal server error" }, "error_type": "server" } }

  2. response.error — ошибка во время генерации ответа:

    json
    { "type": "response.error", "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded" } }

  3. error — обычное событие ошибки (соответствует поведению OpenAI):

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

Преобразования кодов ошибок

Некоторые ошибки, связанные с токенами/длиной, преобразуются в успешные завершения вместо сбоев:

error_typeПреобразовано вПричина завершения
context_length_exceededSuccesslength
max_tokens_exceededSuccesslength
token_limit_exceededSuccesslength
string_too_longSuccesslength

Это позволяет элегантно обрабатывать ошибки, связанные с лимитами, без пометки их как неудач.

Anthropic Messages (/api/v1/messages)

Скин Anthropic Messages отображает внутренние типы в строки ошибок Anthropic:

Внутренний error_typeAnthropic error.type
authenticationauthentication_error
permission_deniedpermission_error
payment_requiredbilling_error
not_found, image_not_foundnot_found_error
rate_limit_exceededrate_limit_error
provider_overloadedoverloaded_error
timeouttimeout_error
context_length_exceeded, content_policy_violation, invalid_request, ...invalid_request_error
provider_unavailable, server, unmapped, ...api_error

Поскольку нативный error.type является потерянным (многие внутренние типы сводятся к api_error), канонический error_type добавляется внутри объекта error рядом с ним. Это справедливо как для не‑стримингового конверта ошибки, так и для SSE‑события error.

Не‑стриминговый конверт ошибки (ошибки до роутера, такие как ошибки аутентификации, имеют request_id: null; пост‑роутерные ошибки содержат gen-‑идентификатор):

json
{ "type": "error", "error": { "type": "authentication_error", "message": "Invalid credentials", "error_type": "authentication" }, "request_id": null }

Ошибки посередине потока отправляются как SSE‑событие error с тем же форматом:

json
{ "type": "error", "error": { "type": "overloaded_error", "message": "Provider is temporarily overloaded", "error_type": "provider_overloaded" } }

Отладка

API VEGA предоставляет параметр debug, позволяющий вам увидеть точное тело запроса, отправленное upstream‑провайдеру. Это работает как с Chat Completions API (/api/v1/chat/completions), так и с Responses API (/api/v1/responses). Полезно для понимания того, как API VEGA трансформирует ваши параметры запроса для разных провайдеров.

Структура параметра debug

Параметр debug — объект со следующей структурой:

typescript
type DebugOptions = { echo_upstream_body?: boolean; // Если true, возвращает трансформированное тело запроса, отправленное провайдеру };

Использование

Чтобы включить вывод отладки, добавьте параметр debug в ваш запрос:

Chat Completions

typescript
fetch('https://openrouter.ai/api/v1/chat/completions', { method: 'POST', headers: { Authorization: 'Bearer <OPENROUTER_API_KEY>', 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'anthropic/claude-haiku-4.5', stream: true, // Отладка работает только со стримингом messages: [ { role: 'system', content: 'You are a helpful assistant.' }, { role: 'user', content: 'Hello!' }, ], debug: { echo_upstream_body: true, }, }), }); const text = await response.text(); for (const line of text.split('\n')) { if (!line.startsWith('data: ')) continue; const data = line.slice(6); if (data === '[DONE]') break; const parsed = JSON.parse(data); if (parsed.debug?.echo_upstream_body) { console.log('\nDebug:', JSON.stringify(parsed.debug.echo_upstream_body, null, 2)); } process.stdout.write(parsed.choices?.[0]?.delta?.content ?? ''); }
python
import requests import json response = requests.post( url="https://openrouter.ai/api/v1/chat/completions", headers={ "Authorization": "Bearer <OPENROUTER_API_KEY>", "Content-Type": "application/json", }, data=json.dumps({ "model": "anthropic/claude-haiku-4.5", "stream": True, "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Hello!" } ], "debug": { "echo_upstream_body": True } }), stream=True ) for line in response.iter_lines(): if line: text = line.decode('utf-8') if 'echo_upstream_body' in text: print(text)

Responses API

typescript
fetch('https://openrouter.ai/api/v1/responses', { method: 'POST', headers: { Authorization: 'Bearer <OPENROUTER_API_KEY>', 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'anthropic/claude-haiku-4.5', stream: true, input: 'Hello!', debug: { echo_upstream_body: true, }, }), }); const text = await response.text(); for (const line of text.split('\n')) { if (!line.startsWith('data: ')) continue; const data = line.slice(6); if (data === '[DONE]') break; const parsed = JSON.parse(data); if (parsed.type === 'response.debug') { console.log('\nDebug:', JSON.stringify(parsed.debug, null, 2)); } }
python
import requests import json response = requests.post( url="https://openrouter.ai/api/v1/responses", headers={ "Authorization": "Bearer <OPENROUTER_API_KEY>", "Content-Type": "application/json", }, data=json.dumps({ "model": "anthropic/claude-haiku-4.5", "stream": True, "input": "Hello!", "debug": { "echo_upstream_body": True } }), stream=True ) for line in response.iter_lines(): if line: text = line.decode('utf-8') if 'response.debug' in text: print(text)

Формат ответа отладки

Chat Completions

Когда debug.echo_upstream_body установлен в true, API VEGA отправляет отладочный чанк первым в стриминговом ответе. Этот чанк имеет пустой массив choices и включает поле debug с трансформированным телом запроса:

json
{ "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, "temperature": 1 } } }

Responses API

В Responses API отладочные данные приходят как SSE‑событие response.debug:

json
{ "type": "response.debug", "debug": { "echo_upstream_body": { "model": "claude-haiku-4-5-20251001", "messages": [ { "role": "user", "content": "Hello!" } ], "stream": true, "max_tokens": 64000, "temperature": 1 } }, "sequence_number": 0 }

Важные замечания

Только стриминг

Параметр debug работает только в режиме стриминга (stream: true). Запросы без стриминга игнорируют параметр отладки.

Не для продакшна

Флаг отладки не следует использовать в продакшн‑окружениях. Он предназначен исключительно для разработки и отладки, так как может раскрывать чувствительные данные, включённые в запрос, которые не предназначены для публичного доступа.

Сценарии использования

Отладочный вывод особенно полезен для:

  1. Понимания трансформаций параметров: увидеть, как API VEGA преобразует ваши параметры в формат, специфичный для провайдера (например, как задаётся max_tokens, как обрабатывается temperature).
  2. Проверки форматирования сообщений: убедиться, как API VEGA объединяет и форматирует ваши сообщения для разных провайдеров (например, как склеиваются system‑сообщения, как объединяются пользовательские сообщения).
  3. Проверки применённых значений по умолчанию: увидеть, какие значения по умолчанию подставляет API VEGA, если параметры не указаны в запросе.
  4. Отладки переключения провайдеров: при использовании fallback‑провайдеров отладочный чанк будет отправлен для каждого попытанного провайдера, позволяя увидеть, какие провайдеры были пробованы и какие параметры были отправлены каждому.

Конфиденциальность и редактирование

API VEGA приложит все усилия для автоматического редактирования потенциально чувствительных или шумных данных в отладочном выводе. Помните, что параметр отладки не предназначен для продакшна.