> Для получения чистого Markdown любой страницы добавьте .md к URL‑адресу страницы. > Для полного индекса документации см. https://api.vega.chat/docs/llms.txt. > Для полного содержания документации см. https://api.vega.chat/docs/llms-full.txt. > Для интеграции AI‑клиентов (Claude Code, Cursor и др.) подключитесь к серверу MCP по адресу https://api.vega.chat/docs/_mcp/server. # Ошибки и отладка Для ошибок VEGA возвращает JSON‑ответ со следующей структурой: ```typescript type ErrorResponse = { error: { code: number; message: string; metadata?: Record; }; }; ``` HTTP‑ответ будет иметь тот же статус‑код, что и `error.code`, образуя ошибку запроса, если: * Ваш исходный запрос недействителен * Ваш API‑ключ/аккаунт исчерпал кредиты В остальных случаях возвращаемый HTTP‑статус будет `{HTTPStatus.S200_OK}`, а любые ошибки, возникшие во время генерации LLM, будут переданы в теле ответа или как событие SSE. Пример кода для вывода ошибок в JavaScript: ```typescript const request = await fetch('https://api.vega.chat/...'); console.log(request.status); // Будет код ошибки, если модель ещё не начала обработку запроса const response = await request.json(); console.error(response.error?.status); // Будет код ошибки console.error(response.error?.message); ``` ## Коды ошибок * **{HTTPStatus.S400_Bad_Request}**: Bad Request (недействительные или отсутствующие параметры, CORS) * **{HTTPStatus.S401_Unauthorized}**: Неверные учётные данные (сессия OAuth истекла, отключён/недействителен API‑ключ) * **{HTTPStatus.S402_Payment_Required}**: На вашем аккаунте или API‑ключе недостаточно кредитов. Добавьте кредиты и повторите запрос. * **{HTTPStatus.S403_Forbidden}**: Forbidden (недостаточно прав, блокировка guardrail, или флаг модерации) * **{HTTPStatus.S408_Request_Timeout}**: Время вашего запроса истекло * **{HTTPStatus.S429_Too_Many_Requests}**: Вы превысили лимит запросов * **{HTTPStatus.S502_Bad_Gateway}**: Выбранная модель недоступна или мы получили недействительный ответ от неё * **{HTTPStatus.S503_Service_Unavailable}**: Нет доступного провайдера модели, соответствующего вашим требованиям маршрутизации ## Заголовок Retry-After В ответах с кодами `{HTTPStatus.S429_Too_Many_Requests}` и `{HTTPStatus.S503_Service_Unavailable}` VEGA может включать стандартный HTTP‑заголовок `Retry-After`, указывающий, сколько секунд ждать перед повторной попыткой. ```http HTTP/1.1 429 Too Many Requests Retry-After: 60 ``` OpenAI SDK, Anthropic SDK, Vercel AI SDK и VEGA SDK уже учитывают этот заголовок для backoff. Если вы используете `fetch` напрямую, соблюдайте его перед повтором: ```typescript const res = await fetch('https://api.vega.chat/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`) запрос может быть заблокирован до того, как достигнет провайдера — например, фильтром контента или детектором инъекций prompt, настроенным через [guardrails](/docs/guides/features/guardrails). В этом случае ответ — `403` с сообщением, описывающим причину блокировки: ```json { "error": { "code": 403, "message": "Request blocked: prompt injection patterns detected", "metadata": { "patterns": ["ignore all previous instructions"] } } } ``` Если вы включаете [router metadata](/docs/features/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](/docs/features/router-metadata#pipeline-stages) для полного описания типов стадий и полей. ## Ошибки провайдера Если провайдер модели сталкивается с ошибкой, `error.metadata` будет содержать информацию о проблеме. Структура метаданных: ```typescript type ProviderErrorMetadata = { provider_name: string; // Название провайдера, у которого возникла ошибка raw: unknown; // Необработанная ошибка от провайдера }; ``` ## Когда контент не генерируется Иногда модель может не сгенерировать никакого контента. Это обычно происходит, когда: * Модель разогревается после холодного старта * Система масштабируется для обработки большего количества запросов Время разогрева обычно составляет от нескольких секунд до нескольких минут, в зависимости от модели и провайдера. Если вы сталкиваетесь с постоянными проблемами отсутствия контента, рассмотрите возможность простого механизма повторных попыток или повторите запрос к другому провайдеру/модели с более активной историей. Также имейте в виду, что в некоторых случаях вы всё равно можете быть начислены за обработку подсказки upstream‑провайдером, даже если контент не был сгенерирован. ## Форматы ошибок при потоковой передаче При использовании потокового режима (`stream: true`) ошибки обрабатываются по‑разному в зависимости от момента их возникновения: ### Ошибки до начала потока Ошибки, возникшие до отправки любых токенов, следуют стандартному формату ошибки, описанному выше, с соответствующими HTTP‑кодами. ### Ошибки в середине потока Ошибки, возникшие после начала потоковой передачи, отправляются как Server‑Sent Events (SSE) с унифицированной структурой, включающей детали ошибки и объект завершения: ```typescript type MidStreamError = { id: string; object: 'chat.completion.chunk'; created: number; model: string; provider: string; error: { code: string | number; message: string; }; choices: [{ index: 0; delta: { content: '' }; finish_reason: 'error'; native_finish_reason?: string; }]; }; ``` Пример данных SSE: ```text data: {"id":"cmpl-abc123","object":"chat.completion.chunk","created":1234567890,"model":"openai/gpt-4o","provider":"openai","error":{"code":"server_error","message":"Provider disconnected"},"choices":[{"index":0,"delta":{"content":""},"finish_reason":"error"}]} ``` Ключевые характеристики: * Ошибка появляется **на верхнем уровне** вместе со стандартными полями ответа * В массиве `choices` присутствует `finish_reason: "error"` для корректного завершения потока * HTTP‑статус остаётся 200 OK, так как заголовки уже отправлены * После этого события поток завершается ## События ошибок API Responses OpenAI API Responses OpenAI (`/api/v1/responses`) использует специальные типы событий для потоковых ошибок: ### Типы событий ошибок 1. **`response.failed`** — официальное событие неудачи ```json { "type": "response.failed", "response": { "id": "resp_abc123", "status": "failed", "error": { "code": "server_error", "message": "Internal server error" } } } ``` 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" } } ``` ### Преобразования кодов ошибок Responses API преобразует некоторые коды ошибок в успешные завершения с определёнными `finish_reason`: | Код ошибки | Преобразуется в | Finish Reason | | ------------------------- | -------------- | ------------- | | `context_length_exceeded` | Success | `length` | | `max_tokens_exceeded` | Success | `length` | | `token_limit_exceeded` | Success | `length` | | `string_too_long` | Success | `length` | Это позволяет элегантно обрабатывать ошибки, связанные с лимитами, без пометки их как неудач. ## Обработка ошибок в разных API Разные эндпоинты VEGA обрабатывают ошибки по‑разному: ### OpenAI Chat Completions API (`/api/v1/chat/completions`) * **Без отправки токенов**: возвращает отдельный `ErrorResponse` * **С отправкой некоторых токенов**: встраивает информацию об ошибке в массив `choices` окончательного ответа * **Потоковая передача**: ошибки отправляются как SSE‑события с полем ошибки на верхнем уровне ### OpenAI Responses API (`/api/v1/responses`) * **Преобразования ошибок**: некоторые ошибки становятся успешными ответами с соответствующими `finish_reason` * **Потоковые события**: используют типизированные события (`response.failed`, `response.error`, `error`) * **Грациозное деградирование**: обрабатывает ошибки провайдера с fallback‑поведением ### Типы ответов ошибок ```typescript // Стандартный ответ об ошибке interface ErrorResponse { error: { code: number; message: string; metadata?: Record; }; } // Ошибка в середине потока с данными завершения interface StreamErrorChunk { error: { code: string | number; message: string; }; choices: Array<{ delta: { content: string }; finish_reason: 'error'; native_finish_reason: string; }>; } // Событие ошибки Responses API interface ResponsesAPIErrorEvent { type: 'response.failed' | 'response.error' | 'error'; error?: { code: string; message: string; }; response?: { id: string; status: 'failed'; error: { code: string; message: string; }; }; } ``` ## Отладка VEGA предоставляет параметр `debug`, позволяющий просмотреть точное тело запроса, отправленное upstream‑провайдеру. Это полезно для понимания того, как VEGA трансформирует ваши параметры для работы с разными провайдерами. ### Структура параметра debug Параметр `debug` — объект со следующей формой: ```typescript type DebugOptions = { echo_upstream_body?: boolean; // Если true, возвращает трансформированное тело запроса, отправленное провайдеру }; ``` ### Использование Чтобы включить вывод отладки, добавьте параметр `debug` в ваш запрос: ```typescript title="TypeScript" fetch('https://api.vega.chat/api/v1/chat/completions', { method: 'POST', headers: { Authorization: 'Bearer ', '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 title="Python" import requests import json response = requests.post( url="https://api.vega.chat/api/v1/chat/completions", headers={ "Authorization": "Bearer ", "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) ``` ### Формат ответа отладки Когда `debug.echo_upstream_body` установлен в `true`, 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 } } } ``` ### Важные замечания Параметр отладки **работает только в потоковом режиме** (`stream: true`) для API Chat Completions. Запросы без потоковой передачи и запросы к Responses API игнорируют параметр `debug`. Флаг отладки **не следует использовать в продакшн‑окружениях**. Он предназначен исключительно для разработки и отладки, так как может вернуть чувствительную информацию, включённую в запрос, которая не должна быть видна в других местах. ### Сценарии использования Отладочный вывод особенно полезен для: 1. **Понимания трансформаций параметров**: увидеть, как VEGA преобразует ваши параметры в форматы, специфичные для провайдера (например, как задаётся `max_tokens`, как обрабатывается `temperature`). 2. **Проверки форматирования сообщений**: убедиться, как VEGA объединяет и форматирует ваши сообщения для разных провайдеров (например, как конкатенируются системные сообщения, как объединяются пользовательские сообщения). 3. **Проверки применённых значений по умолчанию**: увидеть, какие значения по умолчанию применяет VEGA, если параметры не указаны в запросе. 4. **Отладки провайдерных fallback‑ов**: при использовании fallback‑ов провайдеров отладочный чанк будет отправлен **для каждого попытного провайдера**, позволяя увидеть, какие провайдеры были пробованы и какие параметры были отправлены каждому. ### Конфиденциальность и редактирование VEGA приложит все усилия для автоматического редактирования потенциально чувствительных или шумных данных в отладочном выводе. Помните, что параметр отладки не предназначен для продакшн‑использования.