Genius-bot · 12 минут чтения
При интеграции через api нейросети большая часть проблем возникает не на этапе запуска модели, а вокруг HTTP-запроса: неверный ключ, нулевой баланс, слишком частые обращения или неподходящий файл. Если заранее разделить эти случаи по кодам ответа, обработчик ошибок получается заметно проще. Ключ для API можно получить в разделе API после входа.
Удобно считать ошибку частью обычного протокола работы приложения. Клиент отправляет запрос, проверяет HTTP-код, извлекает сообщение из ответа, показывает пользователю понятную причину и записывает технические детали в журнал. При этом 401, 402 и 429 требуют разных действий: повторять запрос сразу после 401 обычно бессмысленно, а после 429 повтор с задержкой может решить проблему.
Ниже разберём коды по сценариям, которые встречаются при работе с генерацией, загрузкой файлов и совместимыми с OpenAI маршрутами. Для каждого случая отдельно рассмотрим, что должен увидеть пользователь и какие данные стоит сохранить в логе, чтобы не диагностировать одну и ту же проблему вслепую.
1. Как читать ответ об ошибке и что в нём важно
HTTP-код — первый признак, по которому стоит выбирать обработчик. Код 4xx означает, что запрос нельзя нормально выполнить в его текущем виде: проблема может быть в авторизации, балансе, частоте запросов, размере файла или параметрах. Но одного номера недостаточно, поэтому полезно сохранять и тело ответа.
Для API используются запросы к адресу https://genius-bot.ru/wp-json/genius/v1. Авторизация передаётся заголовком Authorization: Bearer <ключ>. Например, проверку доступных операций можно выполнить так:
curl -i \
-H "Authorization: Bearer $GENIUS_API_KEY" \
https://genius-bot.ru/wp-json/genius/v1/servicesВ журнале минимум стоит фиксировать HTTP-код, маршрут, время запроса, внутренний идентификатор задачи, если он уже был получен, и текст ошибки из ответа. Сам секретный ключ записывать не нужно. Если приложение работает с файлами, добавьте имя операции, размер файла и тип передаваемого контента.
Полезно также различать ошибку при отправке запроса и ошибку уже созданной задачи. Маршрут POST /generate запускает операцию, а GET /tasks/{id} позволяет получить состояние и результат. Поэтому успешный HTTP-ответ на запуск ещё не означает, что сама задача завершилась успешно.
Для прикладного кода удобно свести обработку к нескольким категориям:
| Код или ситуация | Типичная причина | Действие клиента |
|---|---|---|
| 401 | Неверный или отсутствующий ключ | Проверить ключ и заголовок Authorization |
| 403 | Доступ по текущим данным авторизации отклонён | Проверить ключ и права доступа, не делать бесконечные повторы |
| 402 | Недостаточно средств | Показать необходимость пополнения баланса |
| 429 | Превышена частота запросов | Уменьшить частоту и повторить после задержки |
| 413 | Слишком большой файл | Уменьшить файл или изменить способ подготовки входных данных |
| 422 | Параметры запроса не подходят | Исправить входные данные и повторить |
Такая схема особенно полезна, если один клиент вызывает несколько операций. В API есть отдельные маршруты для загрузки файла, запуска операции и получения результата: POST /uploads, POST /generate и GET /tasks/{id}. Обработчик ошибок лучше строить вокруг HTTP-кода, а не вокруг текста конкретного сообщения.
2. 401 и 403: ключ не тот или отозван
Ошибка 401 означает, что сервер не принял авторизацию запроса. В первую очередь проверьте наличие заголовка Authorization, формат Bearer <ключ> и значение ключа. Если в приложении переменная окружения пуста, результат будет таким же, как при передаче неправильного секрета.
Ключ выдаётся в разделе API после входа и показывается один раз. Поэтому в коде лучше хранить его в переменной окружения или в секрет-хранилище приложения, а не прописывать непосредственно в исходнике. При диагностике достаточно логировать факт наличия ключа, но не его значение.
Минимальный Python-клиент для проверки авторизации может выглядеть так:
import os
import requests
api_key = os.environ["GENIUS_API_KEY"]
response = requests.get(
"https://genius-bot.ru/wp-json/genius/v1/services",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
print(response.status_code)
print(response.text)Если здесь приходит 401, сначала проверяйте конфигурацию приложения, а не параметры конкретной нейросетевой операции. Частая практическая ошибка — передать ключ без слова Bearer или случайно взять старое значение из локального файла окружения.
Код 403 стоит обрабатывать отдельно. Это отказ в доступе, который не следует превращать в бесконечный цикл повторных запросов: десять одинаковых запросов с теми же данными не исправят проблему авторизации.
Для пользователя сообщение должно быть коротким и понятным: «Не удалось выполнить запрос из-за авторизации. Проверьте API-ключ в настройках приложения». В журнале при этом полезны код, маршрут, время, идентификатор клиента или сессии и результат проверки конфигурации, но не сам ключ.
Если вы видите формулировку «api нейросети ошибка 401», ищите причину в цепочке авторизации: переменная окружения → значение ключа → заголовок → URL запроса. Не стоит менять параметры генерации, размер изображения или текст промпта, пока базовый запрос к API не проходит проверку.
3. 402: деньги кончились в середине дня
Код 402 нужно рассматривать как отдельный сценарий, связанный с оплатой операции. В сервисе списание происходит за запуск, без абонентской платы и минимального платежа. При выпуске первого ключа на баланс начисляется 50 ₽ для пробы.
Стоимость зависит от выбранной операции. Например, картинка по описанию стоит 9 ₽ за запуск, расшифровка записи — 10 ₽, озвучка текста — 18 ₽ за 1000 знаков, а видео по описанию — 119 ₽.
| Операция | Цена |
|---|---|
| Картинка по описанию (image) | 9 ₽ за запуск |
| Расшифровка записи (stt) | 10 ₽ за запуск |
| Озвучка текста (tts) | 18 ₽ за 1000 знаков |
| Оживить фото (photo-video) | 25 ₽ за запуск |
| Изменить фото по описанию (image-edit) | 35 ₽ за запуск |
| Убрать шум (denoise) | 36 ₽ за запуск |
| Убрать вокал (vocal) | 45 ₽ за запуск |
| Увеличить качество фото (upscale) | 50 ₽ за запуск |
| Создать музыку (music) | 59 ₽ за запуск |
| Видео по описанию (video) | 119 ₽ за запуск |
| Говорящий аватар (avatar) | 120 ₽ за запуск |
Проверять остаток можно через GET /balance. Это полезно делать до запуска дорогой операции, если приложение формирует пользовательские задания автоматически. Но даже предварительная проверка не отменяет обработки 402: между чтением баланса и фактическим запуском может пройти время.
В интерфейсе ошибка должна объясняться без технического текста: «Недостаточно средств для запуска операции. Проверьте баланс». Если приложение показывает стоимость операции, можно добавить её к сообщению, чтобы пользователь понимал, сколько требуется для следующего запуска.
В журнале сохраняйте код 402, маршрут, название операции, рассчитанную стоимость, время и идентификатор пользователя или внутренней задачи. Полезно также записывать баланс, если приложение само его запрашивало перед запуском. Слово «не хватает средств api» в техническом поиске обычно сводится именно к проверке баланса и стоимости конкретной операции.
4. 429: слишком часто — и как перестать
Для одного ключа установлено ограничение не более 60 запросов в минуту. Ошибка 429 появляется, когда приложение превышает этот предел. Важно считать именно запросы, а не только успешные генерации: проверки статуса, загрузки и другие обращения также являются HTTP-запросами.
Особенно легко получить 429 в системе с опросом задач. Например, если 20 задач проверяются раз в 10 секунд, один только polling создаёт до 120 запросов в минуту. Если параллельно приложение отправляет новые задачи, лимит достигается ещё быстрее.
Первое исправление — увеличить интервал между проверками. Второе — использовать webhook: при запуске операции можно передать параметр callback_url, после чего POST приходит на указанный адрес, когда задача готова. Это позволяет не спрашивать GET /tasks/{id} каждые несколько секунд.
Если 429 уже получен, не нужно немедленно отправлять тот же запрос десятки раз. Для автоматического клиента подходит повтор с задержкой, например с экспоненциальным увеличением интервала и небольшим случайным разбросом. При этом число повторов должно быть ограничено.
import time
import requests
url = "https://genius-bot.ru/wp-json/genius/v1/services"
headers = {"Authorization": f"Bearer {api_key}"}
for attempt in range(4):
response = requests.get(url, headers=headers, timeout=30)
if response.status_code != 429:
response.raise_for_status()
print(response.json())
break
time.sleep(2 ** attempt)В реальном приложении такой цикл лучше вынести в общий HTTP-клиент. Тогда одна политика повторов применяется ко всем подходящим маршрутам, а в логах можно отдельно увидеть исходный 429 и номер попытки.
Пользователю не требуется показывать внутренний счётчик запросов. Достаточно сообщения вроде «Слишком много запросов. Повторите через несколько секунд». В журнале сохраняйте код, маршрут, время, тип операции, номер попытки и сведения о частоте запросов за предыдущий интервал.
Таким образом, «ошибка 429 api» — это не повод менять API-ключ или пополнять баланс. Сначала проверьте частоту запросов, особенно polling статусов, параллельные задачи и повторные попытки после других ошибок.
5. 413 и 422: файл и параметры не подошли
Код 413 относится к размеру входного запроса или файла. Для сценариев, где пользователь передаёт изображение, аудио или другой файл, не стоит пытаться лечить такую ошибку повторной отправкой того же байтового массива: запрос останется слишком большим.
Файлы можно передавать через POST /uploads, который используется для загрузки файла и получения ссылки. После этого ссылка может участвовать в дальнейшей операции. В приложении удобно проверять размер файла ещё до загрузки и отклонять явно слишком крупные входные данные на своей стороне, если ваши бизнес-правила это позволяют.
В сообщении пользователю лучше указать конкретное действие: «Файл слишком большой. Уменьшите его размер и загрузите снова». В журнале сохраняйте размер файла, MIME-тип, маршрут и код ответа. Сам файл или его содержимое не нужно помещать в обычный текстовый лог.
Код 422 обычно означает, что сервер получил запрос, но параметры не подходят для выполнения операции. Причина может быть в отсутствующем обязательном поле, неверном типе значения, несовместимом сочетании параметров или некорректной ссылке на входной файл. Здесь повторять запрос без изменений также бессмысленно.
Обработчик 422 должен вернуть пользователю сообщение о необходимости проверить параметры операции. В журнале полезно сохранить название операции и безопасную копию переданных параметров. Секреты, токены и другие чувствительные значения из журнала нужно исключать.
Для диагностики таких ошибок помогает разделение этапов. Сначала приложение загружает файл через /uploads, затем запускает /generate, после чего получает состояние через /tasks/{id}. Если ошибка возникла на втором шаге, не стоит искать проблему в polling третьего шага.
В API есть операции с разной стоимостью и разными типами входных данных: от генерации изображения и музыки до расшифровки, озвучки и работы с видео. Поэтому универсальный валидатор параметров лучше строить по типу операции, а не использовать один набор полей для всех запросов.
6. Отказ модели: когда повтор помогает, а когда нет
Отдельный сценарий — запрос технически корректен, авторизация работает, баланс есть, лимит частоты не превышен, но сама операция не дала ожидаемого результата. Здесь важно сначала определить, относится ли проблема к временной ошибке выполнения или к входным данным.
Повтор может иметь смысл, если причина выглядит временной и исходные параметры не изменились. Но бесконечно повторять один и тот же запрос нельзя: каждый запуск операции может иметь стоимость, а повторение некорректного входа только увеличивает число неудачных попыток.
Перед повтором проверьте состояние задачи через GET /tasks/{id}, если задача уже получила идентификатор. Это позволяет отличить ситуацию, когда приложение потеряло соединение после успешного запуска, от ситуации, когда запуск действительно завершился ошибкой.
При повторном запуске важно учитывать экономику операции. Например, «Создать музыку» стоит 59 ₽ за запуск, «Видео по описанию» — 119 ₽, а «Говорящий аватар» — 120 ₽. Автоматический retry без ограничения попыток здесь может привести к нескольким платным запускам одного пользовательского действия.
Для пользователя сообщение должно описывать результат, а не внутреннюю архитектуру: «Операцию не удалось завершить. Попробуйте повторить запрос» — если повтор действительно допустим. Если параметры явно некорректны, лучше сообщить, что нужно изменить входные данные.
В журнале сохраняйте идентификатор задачи, операцию, HTTP-код, время запуска, финальное состояние, номер попытки и безопасное представление параметров. Это позволяет после сбоя восстановить последовательность: загрузка файла → запуск → проверка статуса → результат или ошибка.
Если приложение использует совместимый формат OpenAI, доступны маршруты POST /chat/completions и GET /models. В клиентской библиотеке в таком случае достаточно изменить base_url и ключ. Для чата тариф составляет 40 ₽ за млн токенов запроса и 400 ₽ за млн токенов ответа.
Но для обработки ошибок принцип остаётся тем же: сначала смотрим HTTP-код, затем тело ответа и состояние операции, а после этого выбираем действие. Это и есть практическая основа надёжного клиента для api нейросети: не маскировать ошибку повтором, а понимать, какое условие нужно изменить.
Частые вопросы
Что делать, если API возвращает 401?
Проверьте наличие заголовка Authorization: Bearer <ключ> и актуальность ключа. Ключ выдаётся в разделе API после входа и показывается один раз, поэтому его лучше хранить в защищённой конфигурации приложения.
Почему появляется 402, хотя утром запросы работали?
Оплата выполняется за запуск, поэтому баланс может закончиться после нескольких операций. Проверьте остаток через GET /balance и сопоставьте его со стоимостью нужной операции.
Как убрать ошибку 429?
Не превышайте 60 запросов в минуту на один ключ. Уменьшите частоту polling, ограничьте параллельные запросы и для готовых задач рассмотрите использование callback_url, чтобы получать POST после завершения.
Нужно ли повторять запрос после 413?
Нет, если повторяется тот же слишком большой файл. Сначала уменьшите входной файл или измените процесс подготовки данных, затем отправьте запрос заново.
Что делать с ошибкой 422?
Проверьте параметры конкретной операции, типы значений и данные файла. Повтор без изменения входных данных обычно не решает проблему, поэтому сначала исправьте запрос.
Что записывать в лог при ошибке?
Минимальный набор — время, маршрут, HTTP-код, операция, идентификатор задачи при наличии, номер попытки и безопасное представление параметров. API-ключ и другие секретные значения в журнал записывать не следует.
Документацию и управление ключами удобно держать под рукой в личном разделе API. Для диагностики достаточно выстроить обработку вокруг нескольких понятных классов: авторизация, баланс, частота, входные данные и состояние задачи.
