Коды ошибок

Все эндпоинты публичного API отвечают одним и тем же конвертом — по нему можно писать общий обработчик ошибок один раз и переиспользовать на всех запросах. На этой странице — формат конверта и полный список кодов.

Формат ответа

Успешный ответ оборачивается в data (плюс meta у списков — page, per_page, total):

{
  "data": { "id": 4821 },
  "meta": { "page": 1, "per_page": 20, "total": 187 }
}

Ошибка — в error, с машинным code, человекочитаемым message и опциональным fields:

{
  "error": {
    "code": "group_full",
    "message": "В группе нет свободных мест.",
    "fields": { "group_id": "переполнена" }
  }
}

fields присутствует не всегда — только когда ошибку можно привязать к конкретному полю запроса (ошибки валидации, reason у 401).

Список кодов

Код	HTTP	Когда возникает	Что делать
unauthorized	401	Заголовка Authorization нет, ключ не начинается с bb_, неизвестен, отозван или истёк. fields.reason ∈ missing_or_malformed_key, unknown_key, revoked_key, expired_key	Проверить заголовок и статус ключа в разделе интеграций
insufficient_scope	403	Скоуп ключа не покрывает метод (например, read-ключ на write-эндпоинт)	Выпустить ключ со скоупом write либо использовать ключ с нужным скоупом
rate_limit_exceeded	429	Превышен лимит 120 запросов в минуту на этот ключ	Подождать Retry-After секунд, см. «Лимиты запросов»
validation_failed	422	Тело или параметры запроса не прошли валидацию — на POST /leads, POST /demo-lessons, POST /students/{id}/groups	Смотреть fields, поправить запрос
not_found	404	GET /students/{id} — ученика с таким id нет в школе владельца ключа	Проверить id
invalid_window	422	GET /lessons — to раньше from	Поменять даты местами или поправить
window_too_large	422	GET /lessons — окно from..to больше 92 дней	Сократить окно, запрашивать частями
student_not_found	422	POST /students/{id}/groups — ученик не принадлежит этой школе	Проверить id ученика
group_not_found	422	POST /demo-lessons, POST /students/{id}/groups — группа не найдена или не принадлежит этой школе	Проверить group_id
group_full	409	POST /demo-lessons, POST /students/{id}/groups — в группе нет свободных мест	Выбрать другую группу
already_enrolled	422	POST /students/{id}/groups — ученик уже состоит в этой группе	Ничего не делать — зачисление уже есть
funnel_not_found	422	POST /leads — funnel_id не принадлежит этой школе или не существует	Не передавать funnel_id либо передать существующий
missing_idempotency_key	422	Любой write-метод без заголовка Idempotency-Key	Добавить заголовок
idempotency_in_progress	409	Повторный запрос с тем же Idempotency-Key ещё обрабатывается — первый ответ не успел появиться	Повторить запрос чуть позже

Валидация полей

Когда тело запроса не проходит проверку, fields содержит сообщение по каждому полю. Например, для POST /demo-lessons без user_id и lead_id:

{
  "error": {
    "code": "validation_failed",
    "message": "Нужен student_id (user_id) или lead_id.",
    "fields": { "user_id": "обязателен, если не передан lead_id" }
  }
}

Идемпотентность

Idempotency-Key обязателен на всех write-методах (POST /leads, POST /demo-lessons, POST /students/{id}/groups) — подробнее в разделе конкретного запроса в справочнике API. Без заголовка запрос не выполняется:

{
  "error": {
    "code": "missing_idempotency_key",
    "message": "Заголовок Idempotency-Key обязателен для write-методов.",
    "fields": { "Idempotency-Key": "обязателен" }
  }
}

Если повторный запрос с тем же ключом идемпотентности приходит, пока первый ещё не завершился, и ответ не успевает появиться за короткое ожидание, платформа отвечает 409:

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "Запрос с этим Idempotency-Key ещё обрабатывается, повторите чуть позже."
  }
}

Повтор в течение 24 часов

Запрос с тем же (ключ API, Idempotency-Key, эндпоинт) в течение 24 часов возвращает готовый результат первого выполнения — операция повторно не выполняется. Для новой операции используйте новый Idempotency-Key.