Ошибки и повторы

Коды

Код	Что произошло	Что делать
`400`	запрос понят, но неверен по смыслу (пустой текст, неизвестный `doc_type`)	исправить запрос
`401`	токен неверен, отозван или просрочен	выпустить новый в приложении
`402`	исчерпан месячный лимит тарифа	ждать периода или менять тариф
`404`	объекта нет, он чужой или лежит в закрытой зоне «Скрытые»	см. ниже
`409`	конфликт версий при сохранении содержимого	перечитать `base_version` и повторить
`415`	тип файла не поддержан этой операцией	другой формат
`422`	тело не прошло валидацию	смотреть `detail` — там поле и причина
`429`	превышен лимит запросов в минуту	пауза и повтор
`500` `502` `503`	сбой на нашей стороне	повтор с паузой
`504`	сервер не уложился в дедлайн	не повторять тем же текстом

Что повторять

Наш SDK повторяет осторожно, и это стоит скопировать, даже если вы пишете на другом языке.

Повторяется:

429, 500, 502, 503 — с экспоненциальной паузой (0,5 с → потолок 8 с). Если сервер прислал Retry-After, пауза берётся из него.
Любой метод, если соединение не установилось: запрос заведомо не дошёл до сервера, повторять безопасно даже неидемпотентный POST.

Не повторяется:

504. Это дедлайн сервера, а не сетевой сбой: повтор той же формулировки лишь сожжёт лимит. Переформулируйте вопрос короче или сузьте выборку через object_ids.
Неидемпотентный POST, оборвавшийся на чтении ответа. Байты уже ушли, и операция могла выполниться: повтор загрузит файл дважды или дважды оплатит ответ модели.
Поток агента. POST /v1/agent/chat не перезапускается никогда: он мог отдать (и оплатить) половину токенов, а 503 тут означает «агентный режим выключен» — ждать его повторами бессмысленно, надо уходить на /v1/ask.

Лимит запросов

Окно фиксированное, минута. Считается по владельцу токена (квота зависит от роли аккаунта) и дополнительно по IP — для клиентов без аккаунта. При недоступности нашего Redis лимит не применяется: доступность важнее идеального счётчика.

429 — это «слишком часто», а не «слишком много за месяц». Исчерпание тарифа приходит как 402.

Диагностика

GET /health (без префикса /v1) отвечает без токена и говорит только о том, что процесс жив. GET /v1/usage с вашим токеном — самая быстрая проверка, что ключ рабочий. GET /health/deep (нужен токен) показывает состояние зависимостей и штатно отвечает 503 с телом: перечень в checks — это и есть ответ, ради которого его зовут.