Формат ответа об ошибке, таблица всех кодов, что делать в каждом случае.

Ошибки

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

Формат

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

message — человекочитаемое сообщение (на английском, для совместимости с OpenAI-инструментами).
type — категория. Возможные значения: invalid_request_error, rate_limit_error, api_error.
code — машинный код для программной обработки. Список ниже.

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

HTTP	code	Что значит	Что делать
400	`invalid_request`	Тело запроса не соответствует схеме (пропущенное поле, неверный тип, выход за допустимые границы)	Проверить JSON по Быстрому старту
401	`invalid_api_key`	Ключ отсутствует, отозван, или невалиден	Проверить заголовок `Authorization`, создать новый ключ на /keys
402	`insufficient_balance`	На балансе меньше минимального остатка (100 копеек)	Пополнить через /billing
404	`model_not_found`	Модель с таким `id` не существует или неактивна	Проверить написание, посмотреть /models
429	`daily_limit_exceeded`	Превышен дневной лимит на конкретном ключе (только для служебных)	Дождаться сброса лимита или использовать ключ без лимита
502	`upstream_error`	Провайдер модели вернул ошибку (5xx, контент-фильтр, internal error)	Повторить через несколько секунд; если повторяется — попробовать другую модель
503	`exchange_rate_unavailable`	Курс ЦБ РФ временно недоступен — каталог не отдаёт цены	Повторить через минуту
504	`upstream_timeout`	Провайдер модели не ответил за 120 секунд	Повторить; если повторяется — модель перегружена, попробовать другую

Примеры

401 (нет ключа)

Запрос: curl https://api.hubris.pw/v1/models

{
  "error": {
    "message": "Missing API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

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

{
  "error": {
    "message": "Insufficient balance",
    "type": "invalid_request_error",
    "code": "insufficient_balance"
  }
}

404 (модели не существует)

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

{
  "error": {
    "message": "Model not found: fake-provider/nonexistent",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

502 (апстрим лёг)

{
  "error": {
    "message": "Upstream returned an error",
    "type": "api_error",
    "code": "upstream_error"
  }
}

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

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

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

Стриминг

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

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

Что дальше

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

Ошибки

On this page