API ВЕГА

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

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

api guides

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

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 ВЕГА возвращает JSON‑ответ со следующей структурой:

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

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

  • Ваш исходный запрос недействителен
  • Ваш ключ/аккаунт 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 ВЕГА может включать стандартный заголовок HTTP Retry-After, указывающий количество секунд, которое следует подождать перед повторной попыткой.

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

SDK OpenAI, SDK Anthropic, Vercel AI SDK и SDK API ВЕГА уже учитывают этот заголовок при выполнении backoff. Если вы используете 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‑символами. Если длинее, он будет усечён в середине и заменён на ... provider_name: string; // Имя провайдера, запросившего модерацию model_slug: string; };

Ошибки guardrail

На эндпоинтах инференса (/chat/completions, /responses, /messages) запрос может быть заблокирован до того, как достигнет провайдера — например, фильтром контента или детектором внедрения подсказки, настроенным через guardrails. В таком случае ответ имеет статус 403 с сообщением о причине блокировки. Тело ответа в формате API ВЕГА ниже применяется к /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 ВЕГА нормализует каждую ошибку upstream‑провайдера в стабильный типизированный словарь error_type, описанный в разделе Typed Error Codes. Те же значения error_type описывают, что пошло не так, независимо от того, приходит ли ошибка в теле не‑стримингового ответа или как SSE‑событие в середине потока. Нативные коды протокола (например, error.type Anthropic, error.code Responses) являются приближенными и могут различаться между форматами — error_type остаётся единственным надёжным полем.

Для Chat Completions ошибка провайдера, прерывающая генерацию, передаётся в 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 сообщение заменяется на общее, а provider_code и openrouter_metadata опускаются, однако error_type остаётся (server).

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

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

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

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

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

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

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

Форматы ошибок потоковой передачи

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

Ошибки до начала потока

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

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

Вы увидите такие ошибки при неверных ключах API ВЕГА, некорректных запросах или когда все доступные endpoint провайдеров исчерпаны до начала потока.

Ошибки посередине потока

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

Распространённые причины ошибок посередине потока:

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

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

Ошибки посередине потока отправляются как 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 содержит типизированный код, который удобно использовать в switch‑блоках — см. Typed Error Codes для полного списка
  • В массиве choices присутствует объект с finish_reason: "error" для корректного завершения потока
  • HTTP‑статус остаётся 200 OK, поскольку заголовки уже отданы
  • После этого события поток завершается
  • Для ошибок 500‑го класса error.message заменяется на общее сообщение, а provider_code опускается, чтобы не раскрывать детали upstream

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

Когда ошибка провайдера попадает в ваше приложение, API ВЕГА маркирует её каноническим строковым значением 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 в неудачном ответе, как в событии response.failed, так и в не‑стриминговом JSON‑теле.

Таблицы ниже показывают соответствие error_type и HTTP‑статусов.

Лимиты токенов и длины

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 ВЕГА (например, лимит по кредитам).
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 и повторите запрос.

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

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

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

error_typeHTTP‑статусОписание
invalid_request{HTTPStatus.S400_Bad_Request}Параметр запроса сформирован неверно или отсутствует.
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 ВЕГА).
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 ВЕГА не смог загрузить изображение по указанному 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 может содержаться оригинальный код.

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

API ВЕГА предоставляет три «кожи» 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 на верхнем уровне. Пример коллапса аутентификации:

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Преобразуется вFinish Reason
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.

Не‑стриминговый конверт ошибки (ошибки до Router, такие как аутентификация, имеют null request_id; пост‑Router ошибки несут ID генерации 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 ВЕГА предоставляет параметр debug, позволяющий исследовать точное тело запроса, отправленное upstream‑провайдеру. Это работает как с Chat Completions API (/api/v1/chat/completions), так и с Responses API (/api/v1/responses). Полезно для понимания, как API ВЕГА трансформирует ваши параметры для разных провайдеров.

Структура параметра 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 ВЕГА отправляет отладочный чанк в качестве первого чанка в потоковом ответе. Этот чанк имеет пустой массив 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 ВЕГА преобразует ваши параметры в формат, специфичный для провайдера (например, как задаётся max_tokens, как обрабатывается temperature).
  2. Проверки форматирования сообщений: убедиться, как API ВЕГА объединяет и формирует сообщения для разных провайдеров (например, как склеиваются system‑сообщения, как объединяются пользовательские сообщения).
  3. Проверки применённых значений по умолчанию: увидеть, какие значения по умолчанию добавляет API ВЕГА, если они не указаны в запросе.
  4. Отладки fallback‑провайдеров: при использовании fallback‑маршрутизации отладочный чанк будет отправлен для каждого попытного провайдера, позволяя отследить, какие провайдеры были задействованы и какие параметры к ним отправлялись.

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

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