Ошибки API
Как понять ошибку API, когда исправлять запрос, а когда повторять. Как повторить оплату или отправку без создания дубля.
На этой странице
Если запрос не выполнен, сначала посмотрите код HTTP: например, 401 указывает на проблему с доступом, а 429 на слишком частые запросы. Поле error в ответе уточняет причину. Успешный ответ содержит сами данные, без дополнительной общей обёртки.
Формат ошибки
При ошибке сервер возвращает JSON-объект с одним полем error и текстом сообщения:
{"error":"reaction not found"}
Ориентируйтесь в первую очередь на код состояния HTTP, а текст error используйте для логов и подсказок пользователю.
Коды состояния
| Код HTTP | Что означает |
|---|---|
200 OK | запрос успешен, в теле данные. |
201 Created | создан новый ресурс (часть POST-эндпоинтов). |
204 No Content | успех без тела (часть удалений). |
400 Bad Request | некорректное тело или параметры запроса. |
401 Unauthorized | токен отсутствует, неверен или просрочен; либо маршрут недоступен по персональному токену. |
402 Payment Required | действие упирается в тариф или квоту (например, своё медиа-хранилище требует premium). |
403 Forbidden | токену не хватает нужной области доступа для этого маршрута либо у владельца токена нет нужного права кабинета (missing cabinet right, см. Кабинет токена). |
404 Not Found | ресурс не найден или не принадлежит вам. |
409 Conflict | конфликт состояния (например, дубль уникального значения). Второе значение: запрос с таким Idempotency-Key уже выполняется: см. ниже. |
413 Payload Too Large | тело больше допустимого (см. лимиты). Для запросов с Idempotency-Key порог отдельный и более низкий: 64 КиБ. |
422 Unprocessable Entity | тело синтаксически валидно, но не проходит проверки предметной области. Второе значение: тот же Idempotency-Key уже использован с другим телом: см. ниже. |
429 Too Many Requests | превышен лимит запросов (см. лимиты). |
500 Internal Server Error | внутренняя ошибка сервера; повторите позже. |
Как обрабатывать
Считайте успехом коды 2xx. На 401/403 проверьте токен, его области доступа и права в кабинете. На 429 и 5xx уместен повтор с экспоненциальной задержкой.
На 4xx (кроме 429) повторять запрос без изменений бессмысленно: почините запрос. Кроме одного случая: 409 на запросе с Idempotency-Key означает не «почините запрос», а «та же операция прямо сейчас выполняется». Здесь бросать операцию как раз нельзя: иначе вы посчитаете неудачей платёж или рассылку, которые в этот момент проходят. Повторите тем же ключом, соблюдая Retry-After из ответа.
Повтор денежных операций: Idempotency-Key
Ключ: канонический UUID (в нижнем регистре, с дефисами), например 9b1f0d4c-2f6a-4a5f-9a3f-1f2f3a4b5c6d. Другой формат той же строки не принимается: ответ 400.
Где он работает
Заголовок необязателен, но учитывается на операциях, повтор которых стоит денег или запускает массовую отправку:
POST /api/billing/topup: пополнение баланса;POST /api/billing/subscribe: оформление подписки;POST /api/bots/{botID}/reactions/{reactionID}/broadcast: запуск рассылки.
На двух операторских отправках он, наоборот, обязателен: без него запрос отклоняется с 400:
POST /api/bots/{botID}/users/{userID}/dialog/messages;POST /api/bots/{botID}/support/dialogs/{subscriberID}/templates.
На остальных маршрутах заголовок игнорируется. Не считайте его универсальной защитой от дублей: там, где его нет в списке выше, повтор будет вторым запросом.
Что отвечает сервер
- Тот же ключ, то же тело, операция завершена: сервер возвращает записанный ответ первой попытки: тот же код состояния, то же тело, плюс заголовок
Idempotent-Replay: true. Операция выполняется один раз. Запись живёт неделю. - Тот же ключ, операция ещё выполняется:
409иRetry-After. Повторяйте тем же ключом после указанной паузы; новый ключ здесь как раз и создаст второе списание. - Тот же ключ, другое тело:
422. Это защита от чужого повторного использования ключа: сервер не может знать, какое из двух тел вы имели в виду. Возьмите новый ключ. - Тело больше 64 КиБ:
413. Запросы этих операций маленькие; такой размер означает ошибку на стороне клиента.
Есть ответы, которые ключ намеренно не запоминает: 5xx, 408, 425 и 429. Они означают «запрос не был выполнен», поэтому повтор тем же ключом делает работу заново: как и должен. Запоминались бы они: вы бы получали свой же отказ в ответ на каждую следующую попытку в течение недели, и провести операцию под этим ключом стало бы невозможно.
Как этим пользоваться
- Сгенерируйте UUID до первой попытки и сохраните его рядом с задачей.
- Отправьте запрос с этим ключом.
- При обрыве связи, таймауте,
5xxили429повторяйте тот же ключ, а не новый. - Получив
409, подождитеRetry-Afterи повторите тем же ключом. - Новый ключ берите только для новой, действительно другой операции.
Главная ошибка: генерировать ключ заново на каждой попытке. Так заголовок выглядит настроенным, но не защищает ни от чего: каждая попытка для сервера отдельная операция.
Ошибки ИИ и настройки сценариев
Managed AI возвращает коды причин not_available (функция недоступна),
not_entitled (нет доступа), budget_exceeded (исчерпан бюджет),
rate_limited (превышена частота запросов), provider_unavailable (сервис
модели недоступен) и schema_validation_failed (ответ не прошёл проверку
формата). Повторяйте только ошибки, для которых ответ допускает повтор, с тем
же Idempotency-Key. При ошибке 4xx, кроме 429, или при отказе проверки
схемы исправьте запрос: переключение на другого поставщика модели её не устранит.
Если Copilot вернул stale_base, предложенное изменение реакции устарело:
создайте его заново на основе текущей схемы. Изменение правил анализа
возвращает 409, если правила уже изменил другой запрос. Пересчёт аналитики
и повторное воспроизведение запуска выполняются как задачи с ограниченным
объёмом: проверяйте состояние начатой задачи, прежде чем запускать новую.
Проверка подключения Meta возвращает код причины, по которому можно найти
проблему. Тело ответа Meta и токен доступа в ошибку не включаются.
Что дальше
- Авторизация и токены: про
401и403подробно. - Лимиты и размеры: про
429и ограничения тел. - Интерактивный справочник: какие ошибки возможны у конкретного эндпоинта.