Ошибки и лимиты API
API kosareva.cloud отвечает на ошибку кодом HTTP и объяснением по-русски в error.message. Найдите код в таблице, рядом написано, что случилось и что сделать.
Коды ответов
Ошибки приходят в формате OpenAI, в error.message объяснение по-русски. Запрос, который закончился ошибкой, не списывается.
| Код | Что случилось | Что делать |
|---|---|---|
| 400 | Запрос неверный: нет обязательного поля, модели нет в каталоге, запрос не помещается в контекст | Прочитайте error.message, сверьте имя модели с /v1/models |
| 401 | Ключ не передан, скопирован не целиком или удалён | Проверьте заголовок Authorization и ключ в кабинете |
| 402 | Два случая: на балансе нет денег или достигнут лимит ключа | Пополните баланс или поднимите лимит ключа в разделе «API-ключи» |
| 403 | Модель недоступна этому ключу или аккаунту | Возьмите ключ без ограничений или другую модель |
| 404 | Неверный адрес запроса | Проверьте /v1 в базовом адресе |
| 413 | Запрос больше 25 МБ | Сожмите файл или разделите запрос |
| 429 | Слишком много запросов подряд или модель перегружена | Сделайте паузу и повторите с растущей задержкой |
| 5xx | Временная ошибка на стороне модели или у нас | Повторите запрос, деньги за него не списаны |
Разбор по случаям
Подробные разборы лежат в справочнике, ссылки под каждым случаем.
401: «Ключ не найден», «Ключ не принят» или «Ключ не распознан»
Ключ скопирован не целиком, с пробелом или переносом строки, удалён в кабинете — или передан не в том заголовке. Нужен Authorization: Bearer ВАШ_API_КЛЮЧ; в формате Anthropic подходит и x-api-key. Ключ OpenAI или Anthropic сюда не подходит — только ключ из нашего кабинета.
404: адрес без /v1 или с лишним хвостом
Базовый адрес для OpenAI SDK — ровно https://api.kosareva.cloud/v1: без /v1 запрос уходит мимо API, а с /chat/completions на конце путь удваивается — SDK допишет его сам. Для Anthropic SDK наоборот: https://api.kosareva.cloud без /v1.
«Такой модели нет в каталоге или она переименована»
Имя модели — как в каталоге: латиницей через дефисы, например claude-sonnet-5-5. Вариант через точку или с приставкой вендора (anthropic/…) шлюз приведёт к этому имени сам, если остаток совпал с каталогом. С датой версии, пробелом внутри или опечаткой запрос получит эту ошибку. Точный список отдаёт GET /v1/models.
402: нет денег на балансе или лимит ключа
Ответ «На балансе kosareva.cloud недостаточно средств»: пополните баланс в кабинете картой или СБП, от 50 ₽. Ответ «Достигнут лимит ключа»: деньги есть, а ключ упёрся в свой лимит в рублях, поднимите его в разделе «API-ключи».
Ответ обрывается на полуслове
Модель упёрлась в потолок длины ответа — max_tokens. Поднимите его или попросите модель продолжить. Обратная ошибка — 400 «Запрос не помещается в контекст модели»: потолок ответа вместе с историей не влезает в окно модели. Тогда уменьшите max_tokens или сожмите историю.
429: «Слишком много запросов подряд»
Сделайте паузу и повторите запрос, лучше с растущей задержкой. Если нагрузка постоянная, напишите нам — лимит поднимем.
Долго нет ответа или 504
Длинный ответ без потоковой выдачи идёт минутами, и клиент с коротким таймаутом может сдаться раньше модели: включите stream или поднимите таймаут. Если пришёл наш 504 «Модель не начала отвечать за отведённое время», деньги за такой запрос не списываются — повторите его.
Таймаут и повторы
Рассуждающие модели думают долго, поэтому короткий таймаут клиента рвёт соединение раньше, чем придёт ответ.
- Ставьте таймаут клиента от 120 секунд, для правки картинок от 180 секунд.
- При ответах 5xx заложите две-три попытки с небольшой паузой.
- В интерфейсах включайте потоковую выдачу: первые слова придут сразу.
from openai import OpenAI
client = OpenAI(
api_key="ВАШ_API_КЛЮЧ",
base_url="https://api.kosareva.cloud/v1",
timeout=120,
max_retries=3,
)