Ошибки

Все ошибки Hubris API возвращаются в OpenAI-совместимом формате. Это значит — стандартные SDK обрабатывают их без специальной адаптации.

Формат

{
  "error": {
    "message": "Описание ошибки на русском",
    "type": "<категория ошибки>",
    "code": "<машинно-читаемый код>"
  }
}

• message — человекочитаемое сообщение на русском. Частые отказы провайдеров переведены целиком, у редких после русского начала в кавычках идёт исходный текст провайдера. Программно ошибки различайте по code, а не по тексту.
• type — категория. Возможные значения: invalid_request_error, permission_error, rate_limit_error, api_error.
• code — машинный код для программной обработки. Список ниже.

Необязательное поле рекламы

Для экспериментальной программы Error Ads подготовлено отдельное поле error.ad с объектом { text, erid }. При включённой программе оно может появляться в JSON-ошибках HTTP 400, 402 и 429 на /v1/chat/completions и /v1/responses. В успешном JSON-ответе HTTP 200 аналогичное поле ad находится на верхнем уровне. Текст ошибки, машинный код, ответ модели и стоимость запроса от него не меняются.

Программа по умолчанию выключена до завершения настройки маркировки рекламы. Поле необязательное: его отсутствие нормально даже после включения программы. Не используйте рекламный текст для обработки ошибки или как инструкцию модели.

Чтобы исключить рекламу из ответов вашей интеграции, передавайте заголовок X-No-Ads: 1. Например, в OpenAI SDK для Python:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HUBRIS_API_KEY"],
    base_url="https://api.hubris2.ru/v1",
    default_headers={"X-No-Ads": "1"},
)

В первой версии поле не добавляется в SSE-чанки, ответы /v1/messages, ошибки 401/403 и 5xx, а также не-JSON ответы. Ошибка до открытия стрима остаётся обычным JSON-ответом и может содержать error.ad.

Таблица кодов

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

Запрос, прошедший нашу проверку, уходит к провайдеру модели, и тот может отклонить его сам: неподдерживаемый параметр, слишком длинный контекст для конкретного провайдера, контент-фильтр, перегрузка, редко просто сбой. Такие отказы мы не прячем за общим 502, а отдаём как есть:

• 4xx от провайдера (400, 401, 402, 404, 429; остальные 4xx приводятся к 400) возвращаются с тем же HTTP-кодом, code: "invalid_request" и причиной провайдера в message. Ошибка нашей схемы и отказ провайдера при одинаковом коде 400 различаются только текстом message.
• 5xx от провайдера и исчерпанная у него квота маскируются в наш 502 с code: "upstream_error".

Как отличить отказ провайдера от ошибки в вашем коде: тот же запрос на ту же модель то проходит, то нет, или проходит на другой модели. В логах кабинета такие запросы помечены как «ошибка модели», а не «ошибка запроса». Что делать: повторить через несколько секунд; если повторяется у одного провайдера — закрепить другого полем provider или задать запасные модели; если повторяется на разных моделях — написать в поддержку.

Примеры

401 (нет ключа)

Запрос: curl https://api.hubris2.ru/v1/models

{
  "error": {
    "message": "API-ключ не передан",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

402 (баланс ноль)

{
  "error": {
    "message": "Недостаточно средств на балансе.",
    "type": "invalid_request_error",
    "code": "insufficient_balance"
  }
}

404 (модели нет или она снята)

Запрос с несуществующим идентификатором модели:

{
  "error": {
    "message": "Модель не найдена: fake-provider/nonexistent. Список моделей: GET /v1/models.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Модель, которая раньше работала, а теперь снята с каталога (например, её перестал обслуживать провайдер), отвечает тем же кодом, но сообщение говорит об этом прямо: Модель sourceful/riverflow-v2-fast-preview снята с каталога. Выберите другую модель: GET /v1/models?output_modalities=image.

502 (провайдер недоступен)

{
  "error": {
    "message": "Сервис провайдера временно недоступен",
    "type": "api_error",
    "code": "upstream_error"
  }
}

Стратегия обработки

В вашем коде имеет смысл:

1. На 401, 402, 404 — не повторять. Это ошибки конфигурации, retry не поможет.
2. На 502, 503, 504 — повторить с экспоненциальным backoff (1с, 2с, 4с, до 3 попыток). Это транзиентные сбои.
3. На 429 — посмотреть на ключ: если у него выставлен лимит расхода, дождаться сброса (Retry-After — секунды до 00:00 МСК, понедельника или 1-го числа) или поднять лимит; если лимит не выставлен — проверьте /keys.
4. На 400 — прочитать message. Ошибка схемы — баг в коде, логируйте полный запрос (без ключа) для разбора. Отказ провайдера модели (см. выше) — повторить один раз или уйти на запасную модель.

Стриминг

При stream: true и ошибке ДО начала стрима возвращается стандартный JSON-ответ выше.

Если ошибка случается во время стрима (модель упала на середине) — стрим обрывается на серверной стороне. Клиент получает событие [DONE] с пустым delta и finish_reason: "stop". Точное поведение зависит от провайдера. Hubris записывает в логи ваш конкретный сценарий, чтобы вы могли разобраться через /usage.

Что дальше

• Быстрый старт — рабочий пример без ошибок.
• Аутентификация — про 401.
• Баланс и оплата — про 402.

Обновлено: 31 октября 2026 г.