База знаний GetMyBot

Ошибки 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. Они означают «запрос не был выполнен», поэтому повтор тем же ключом делает работу заново: как и должен. Запоминались бы они: вы бы получали свой же отказ в ответ на каждую следующую попытку в течение недели, и провести операцию под этим ключом стало бы невозможно.

Как этим пользоваться

  1. Сгенерируйте UUID до первой попытки и сохраните его рядом с задачей.
  2. Отправьте запрос с этим ключом.
  3. При обрыве связи, таймауте, 5xx или 429 повторяйте тот же ключ, а не новый.
  4. Получив 409, подождите Retry-After и повторите тем же ключом.
  5. Новый ключ берите только для новой, действительно другой операции.

Главная ошибка: генерировать ключ заново на каждой попытке. Так заголовок выглядит настроенным, но не защищает ни от чего: каждая попытка для сервера отдельная операция.

Ошибки ИИ и настройки сценариев

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 и токен доступа в ошибку не включаются.

Что дальше