РУКОВОДСТВО · ОБНОВЛЕНО 2026-09-16
Ошибки 401, 402 и 429 в API нейросетей: что проверить до повтора
Один и тот же совет «повторите запрос» неприменим к неверному ключу, пустому балансу, ограничению частоты и потерянному соединению.
Сначала прочитайте HTTP-статус и код ошибки в теле ответа. Для 401 проверьте ключ и его права, для 402 — доступный баланс и тариф, для 429 — конкретный лимит и допустимое время ожидания. При таймауте или 5xx выясните состояние исходного запроса до новой генерации; если API поддерживает идемпотентность, повторяйте с тем же ключом операции и неизменным телом.
1. Разделите ошибки авторизации и денег
401 означает, что запрос не прошёл проверку доступа: сверьте способ передачи Bearer-токена, активность ключа и проект. Не печатайте полный ключ в логах. В контракте Tokenmost 402 используется при недостаточном доступном остатке: проверьте баланс и резервирование, а не пытайтесь перебором моделей обойти ограничение. Если тариф выбранной модели не опубликован, сервер может вернуть иную ошибку; ориентируйтесь на фактический ответ метода.
2. Для 429 выясните, какой предел достигнут
Ограничиваться одной секундой ожидания нельзя. Лимит может относиться к числу запросов, токенам за период, проекту или исчерпанной квоте у конкретного API. Смотрите код и сообщение ошибки, Retry-After при наличии, а также текущую нагрузку. Для временного ограничения применяйте ограниченную экспоненциальную паузу с разбросом и общим дедлайном. При исчерпанном бюджете или невалидном доступе повторы не помогут.
3. Отделите HTTP-ответ от сетевого сбоя
Если пришёл JSON с кодом ошибки, сервер обработал запрос до определённой стадии. Если соединение оборвалось без ответа, состояние генерации неизвестно. Повтор с новым идентификатором может создать второй платный вызов. Сохраняйте свой request ID, идентификатор идемпотентности и время попытки. Для потокового ответа отдельно учитывайте частично полученные данные и отмену: автоматическое начало с нуля может дублировать уже выполненную работу.
4. Ограничьте политику повторов в коде
Повторяйте только случаи, для которых контракт метода обещает безопасное поведение. Для Tokenmost платные маршруты требуют Idempotency-Key: это идентификатор одной операции, который сохраняют при повторе того же тела запроса. Новый вопрос пользователя получает новый ключ. Поставьте предел попыток, общий таймаут и защиту от одновременного повтора одной операции в нескольких воркерах. Если итог всё ещё неизвестен, показывайте состояние «требует сверки», а не обещайте, что списания не было.
5. Сделайте таблицу диагностики для команды
Для каждой ошибки зафиксируйте симптом, ответ сервера, вероятную причину, допустимое действие и момент эскалации. В журнале оставляйте статус, безопасный код ошибки, model id, request ID и версию клиента. Проверяйте эти сценарии в песочнице и на моках: неверный ключ, нулевой баланс, превышение лимита, задержка и потеря ответа. Это даёт поддержке конкретный путь решения вместо бесконечного «попробуйте позже».
Частые вопросы
Нужно ли повторять запрос после 401?
Нет, сначала исправьте ключ, заголовок авторизации или права проекта.
Что означает 402 в Tokenmost?
В текущем контракте — недостаточно доступного остатка для резервирования запроса.
Всегда ли 429 лечится ожиданием?
Нет. Изучите код ошибки: часть ограничений требует изменения бюджета или доступа.
Можно ли повторить запрос после таймаута?
Только по правилам конкретного API; при поддержке идемпотентности используйте тот же ключ операции и то же тело.