Для получения чистого 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.

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

MD версия

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

typescript

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

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

Ваш исходный запрос недействителен
Ваш API‑ключ/аккаунт исчерпал кредиты

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

В ответах с кодами <code>{HTTPStatus.S429_Too_Many_Requests}</code> и <code>{HTTPStatus.S503_Service_Unavailable}</code> 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. В этом случае ответ — 403 с сообщением, описывающим причину блокировки:

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 для полного описания типов стадий и полей.

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

Если провайдер модели сталкивается с ошибкой, 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) использует специальные типы событий для потоковых ошибок:

Типы событий ошибок

response.failed — официальное событие неудачи

json

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

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

json

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

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<string, unknown>;
  };
}

// Ошибка в середине потока с данными завершения
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

fetch('https://api.vega.chat/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <VEGA_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://api.vega.chat/api/v1/chat/completions",
  headers={
    "Authorization": "Bearer <VEGA_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)

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

Когда 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.

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

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

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

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

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

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

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

Коды ошибок

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

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

Ошибки guardrail

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

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

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

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

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

События ошибок API Responses OpenAI

Типы событий ошибок

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

Обработка ошибок в разных API

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

OpenAI Responses API (/api/v1/responses)

Типы ответов ошибок

Отладка

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

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

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

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

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

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

OpenAI Chat Completions API (`/api/v1/chat/completions`)

OpenAI Responses API (`/api/v1/responses`)