Ошибки

Все ошибки API возвращаются с HTTP-кодом и телом в JSON. Заголовок ответа всегда `Content-Type: application/json; charset=utf-8`, тексты сообщений — на русском.

Тело устроено одинаково для всех ошибок: машинный код лежит в `detail.error.code`, человекочитаемое пояснение — в `detail.error.message`.

{
  "detail": {
    "error": {
      "code": "insufficient_balance",
      "message": "<текст на русском>"
    }
  }
}

• 429 rate_limited — повторять. Это временное состояние: лимиты считаются поминутно. Делайте паузу с увеличением (1 с, 2 с, 4 с) и добавляйте случайный разброс, чтобы параллельные потоки не били в одну секунду.
• 502 upstream_error — повторять, но ограниченно: 2–3 попытки с паузой. Если ошибка держится, дальнейшие повторы только тратят время.
• 401 no_api_key и 401 invalid_api_key — не повторять. Ключ сам по себе не появится и не восстановится; нужно исправить конфигурацию.
• 402 insufficient_balance — не повторять. Запрос пройдёт только после пополнения баланса. Ставьте задачу в отложенную очередь или уведомляйте ответственного.
• 409 too_many_keys — не повторять. Ошибка возникает при создании ключа и требует действия в кабинете.

Официальная библиотека `openai` бросает `APIStatusError` на любой не-2xx ответ. Разбирать имеет смысл именно `detail.error.code`.

import random
import time
from openai import OpenAI, APIStatusError

client = OpenAI(
    api_key="sk-libra-…",
    base_url="https://api.librachat.kz/v1",
)

RETRIABLE = {"rate_limited", "upstream_error"}


def error_code(exc: APIStatusError) -> str | None:
    try:
        body = exc.response.json()
    except Exception:
        return None
    return body.get("detail", {}).get("error", {}).get("code")


def ask(messages, tries=3):
    for attempt in range(tries):
        try:
            return client.chat.completions.create(
                model="libra-fast",
                messages=messages,
                temperature=0.3,
                max_tokens=1000,
            )
        except APIStatusError as exc:
            code = error_code(exc)
            if code in RETRIABLE and attempt < tries - 1:
                time.sleep(2 ** attempt + random.random())
                continue
            raise


print(ask([{"role": "user", "content": "Привет"}]).choices[0].message.content)

Проверить ключ и связь можно самым дешёвым способом — запросом к списку моделей. Он тоже требует ключ и вернёт 401 при неверном значении.

curl -i https://api.librachat.kz/v1/models \
  -H "Authorization: Bearer sk-libra-…"

• Ошибки нет там, где вы её ждёте. Неподдерживаемые параметры не вызывают ошибку, а молча игнорируются: `tools`, `tool_choice`, `top_p`, `n`, `stop`, `seed`, `response_format`, `presence_penalty`, `frequency_penalty`, `logprobs`, `user`. Запрос вернёт 200, но параметр не подействует.
• Картинки в `messages` (части с `image_url`) тоже молча отбрасываются — ошибки не будет, модель просто их не увидит. Не полагайтесь на код ответа при проверке.
• `max_tokens` вне диапазона 1..32 000 некорректен — держите значение в этих границах.
• В стриминге ошибка может прийти до начала потока. Сам поток завершается строкой `data: [DONE]`, а в последнем фрагменте `choices` пустой (там только `usage`). В Python обязательна проверка `if chunk.choices:` — иначе получите `IndexError`, который легко принять за ошибку сервиса.
• Windows PowerShell 5.1 не всегда правильно распознаёт UTF-8 в ответе, и русские тексты ошибок выглядят кракозябрами. Перед запросом выполните `[Console]::OutputEncoding = [Text.Encoding]::UTF8` или разбирайте `detail.error.code`, а не текст.
• Если хранилище лимитов временно недоступно, ограничения пропускаются и 429 не приходит. Это не повод отключать обработку 429 на стороне клиента.