База знаний GetMyBot

Ошибки API

Единый формат ошибок GetMyBot API, значения кодов состояния HTTP и безопасный повтор денежных операций через Idempotency-Key.

На этой странице

API сообщает об ошибках стандартными кодами состояния HTTP и единым телом ответа. Успешные ответы возвращают данные напрямую, без обёртки-конверта.

Формат ошибки

При ошибке сервер возвращает JSON-объект с одним полем error и текстом сообщения:

{"error":"reaction not found"}

Ориентируйтесь в первую очередь на код состояния HTTP, а текст error используйте для логов и подсказок пользователю.

Коды состояния

  • 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

Обычный повтор безопасен для чтения и опасен для операций, которые чего-то стоят: разорванное соединение не говорит, дошёл ли запрос. Заголовок 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 и workflow

Managed AI использует стабильные codes: not_available, not_entitled, budget_exceeded, rate_limited, provider_unavailable, schema_validation_failed. Повторяйте только retryable ошибки с тем же idempotency key. Не превращайте 4xx/schema error в запрос к другому provider.

Copilot может вернуть stale_base: proposal нужно пересоздать на актуальном графе. Update policy возвращает 409 при optimistic version conflict. Reaggregation и replay – bounded jobs: проверяйте статус существующего job, а не запускайте дубликат. Meta asset check возвращает actionable reason codes; upstream body и access token в ошибку не попадают.

Что дальше