REST API v1 · Разработчикам
Ошибки и коды ошибок
Ошибки всегда приходят в JSON: стабильный машиночитаемый код error и понятное человеку сообщение message. Ориентируйтесь на error и HTTP-статус — текст сообщений предназначен для людей и может меняться.
Документация для разработчиков
На этой странице
Формат ошибки
У всех ответов с ошибкой одна форма: { "error": CODE, "message": "…" }. Некоторые коды добавляют поля, которые помогают отреагировать: например, issues (что именно неверно), required (недостающее право), balance, feature или retryAfter.
HTTP/1.1 400 Bad Request
{
"error": "INVALID_REQUEST",
"message": "Invalid body",
"issues": [{ "path": "body.amount", "message": "Number must be greater than or equal to 1" }]
}HTTP/1.1 409 Conflict
{ "error": "INSUFFICIENT_FUNDS", "message": "The member does not have enough to remove this amount", "balance": 40 }В issues каждый path начинается с части запроса, к которой он относится: params., query., body. или header..
Все коды ошибок
У каждого эндпоинта в справочнике API перечислены коды, которые он может вернуть. Полный список:
| HTTP | Код | Описание |
|---|---|---|
| 400 | INVALID_REQUEST | Неверные ID, параметры, заголовки или тело запроса; в issues — что именно не так |
| 400 | INVALID_JSON | Тело запроса — невалидный JSON |
| 401 | UNAUTHORIZED | Заголовок Authorization отсутствует или имеет неверный формат |
| 401 | INVALID_API_KEY | Такого ключа нет |
| 401 | API_KEY_REVOKED | Ключ отозван в консоли |
| 401 | API_KEY_EXPIRED | Срок действия ключа истёк |
| 402 | PLAN_LIMIT | Тариф сервера этого не покрывает: достигнут лимит (limit) или нет нужной возможности (flag) |
| 403 | BROWSER_REQUESTS_NOT_ALLOWED | Запрос отправлен из браузера (есть заголовок Origin) |
| 403 | GUILD_MISMATCH | Ключ принадлежит другому серверу |
| 403 | INSUFFICIENT_SCOPE | У ключа нет нужного права; оно указано в required |
| 403 | GUILD_BLOCKED | Сервер заблокирован в BotGG |
| 403 | SELF_DECISION | Создатель API-ключа не может сам решать по своей заявке или апелляции |
| 403 | MODERATOR_NOT_MEMBER | Создатель API-ключа больше не состоит на сервере (модерация идёт от его имени) |
| 403 | MODERATOR_MISSING_PERMISSION | У создателя API-ключа нет нужного права Discord; оно указано в required |
| 403 | HIERARCHY | К цели нельзя применить модерацию; причина — в reason (создатель ключа, бот, владелец или роль не ниже роли создателя или бота) |
| 404 | NOT_FOUND | Неизвестный эндпоинт |
| 404 | TICKET_NOT_FOUND | На сервере нет тикета с таким номером |
| 404 | TRANSCRIPT_NOT_FOUND | У тикета нет сохранённой расшифровки (он ещё открыт, расшифровки выключены или удалены) |
| 404 | APPLICATION_NOT_FOUND | На сервере нет заявки (или формы) с таким номером или ID |
| 404 | APPEAL_NOT_FOUND | На сервере нет апелляции с таким номером |
| 404 | CASE_NOT_FOUND | На сервере нет случая модерации с таким номером |
| 404 | MODERATION_ACTION_NOT_FOUND | Действия модерации с таким ID этим API-ключом не делалось |
| 404 | BOT_NOT_IN_GUILD | BotGG нет на этом сервере |
| 404 | MEMBER_NOT_FOUND | Пользователь не состоит на сервере |
| 404 | XP_CHANGE_NOT_FOUND | Изменения опыта с таким ID этим API-ключом не делалось |
| 404 | SHOP_STORE_NOT_FOUND | На сервере нет магазина с таким ID |
| 404 | SHOP_ITEM_NOT_FOUND | На сервере нет товара Магазина с таким ID |
| 404 | SHOP_PURCHASE_NOT_FOUND | На сервере нет покупки с таким ID |
| 404 | GIVEAWAY_NOT_FOUND | На сервере нет розыгрыша с таким ID |
| 404 | FLOW_NOT_FOUND | На сервере нет сценария с таким ID |
| 404 | FLOW_EXECUTION_NOT_FOUND | На сервере нет запуска сценария с таким ID |
| 409 | FEATURE_DISABLED | Модуль, который использует эндпоинт, выключен на сервере; он указан в feature |
| 409 | BANK_DISABLED | Банк на этом сервере выключен |
| 409 | INSUFFICIENT_FUNDS | Недостаточно средств для списания; в balance — текущий баланс |
| 409 | SHOP_ITEM_UNAVAILABLE | Товар сейчас нельзя купить или выдать; причина — в reason (выключен, магазин закрыт, нет в наличии, лимит, цена изменилась, роли, уровень, роль уже есть) |
| 409 | SHOP_ALREADY_REFUNDED | Покупка уже возвращена |
| 409 | SHOP_ITEM_USED | Товар уже использован; верните его с force: true |
| 409 | ROLE_NOT_GRANTABLE | Бот не может выдать роль товара (роли нет, она выше бота, слишком опасна или Discord отказал); деньги не списаны |
| 409 | GIVEAWAY_BAD_STATE | Статус розыгрыша этого не допускает; текущий — в status |
| 409 | FLOW_NOT_RUNNABLE | Запускать можно только сценарии с ручным триггером или триггером «Вебхук»; триггер — в triggerType |
| 409 | FLOW_DISABLED | Сценарий выключен |
| 409 | TICKET_CLOSED | Тикет уже закрыт |
| 409 | ALREADY_DECIDED | По заявке или апелляции уже принято решение; оно в status |
| 409 | NOT_BANNED | Пользователь не забанен на сервере |
| 409 | BOT_MISSING_PERMISSIONS | У бота нет нужного права Discord; оно указано в missing |
| 413 | PAYLOAD_TOO_LARGE | Слишком большое тело запроса |
| 415 | UNSUPPORTED_MEDIA_TYPE | Тело отправлено не как application/json |
| 422 | IDEMPOTENCY_KEY_REUSED | Ключ идемпотентности уже использован для другого запроса |
| 422 | BOT_ACCOUNT | У ботов не может быть баланса |
| 422 | BALANCE_LIMIT | Операция нарушит лимиты баланса на сервере |
| 429 | RATE_LIMITED | Слишком много запросов; подождите Retry-After секунд (то же значение — в поле retryAfter) |
| 500 | INTERNAL | Ошибка на нашей стороне |
| 503 | SERVICE_UNAVAILABLE | Не удалось связаться с Discord, или BotGG временно приостановил модуль; повторите позже |
Какие ошибки повторять
429 RATE_LIMITEDи503 SERVICE_UNAVAILABLE: подождите столько секунд, сколько указано вRetry-After(то же вretryAfter), и повторите.500 INTERNALи сетевые ошибки: повторяйте с нарастающей паузой. Для записи передавайте Idempotency-Key, чтобы повтор никогда не применил изменение дважды.- Остальные ошибки
4xxне исчезнут при повторе того же запроса: сначала исправьте запрос, ключ или настройки сервера.