Справка

Ошибки

Как выглядит ошибка

Любая ошибка приходит с кодом ответа HTTP 4xx или 5xx и телом одного вида:

Code
{
  "code": "quota_exhausted",
  "message": "Квота отдела на смену 3 исчерпана (20 из 20). Добавить места может руководитель — обратитесь к нему",
  "request_id": "r8KfQ2mZx7LpT0aVn3Wd"
}

Поле	Что это
`code`	Машинный код. Не меняется никогда — по нему ваша CRM решает, что делать
`message`	Текст для человека, по-русски. Можно показать менеджеру. Не разбирайте его программой — текст может меняться
`request_id`	Номер запроса (он же в заголовке `X-Request-Id`). Назовите его, когда пишете в лагерь: по нему найдут запрос в журнале

Что делать — по коду ответа

Код ответа	Что значит	Что делать
`400`	Неверный запрос: поле, параметр, формат	Исправить запрос. Повторять тот же запрос бесполезно
`401`	Нет ключа или ключ недействителен	Проверить ключ; если отозван — запросить новый у лагеря
`403`	Нельзя: нет права или так запрещено правилами	Показать `message` менеджеру; при `scope_missing` — попросить право у лагеря
`404`	Записи нет или она не вашего отдела	Проверить номер. Чужая запись неотличима от несуществующей
`405`	Метод не поддерживается по этому адресу	Проверить метод (`GET`/`POST`/`PATCH`/`DELETE`)
`409`	Конфликт с текущим состоянием (нет мест, уже есть счёт, уже отменена)	Показать `message` менеджеру; перечитать запись
`412`	Запись изменили после вашего чтения (`If-Match`)	Перечитать запись, показать менеджеру, повторить
`413`	Тело больше 1 МБ	Уменьшить запрос
`422`	Тело не принято: незнакомое или неверное поле, или ключ повтора с другим телом	Исправить тело (имя поля — в `message`)
`429`	Превышен лимит	Подождать `Retry-After` секунд и повторить (см. Лимиты)
`500`	Внутренняя ошибка лагеря	Повторить позже с тем же `Idempotency-Key`; если повторяется — написать в лагерь с `request_id`
`503`	Сервер не ответил за 30 секунд или часть сервиса недоступна	Повторить с тем же `Idempotency-Key` — см. Повтор запроса

Ответы 401, 403, 429 и 503 возможны у любого адреса.

Отказ запоминается вместе с ключом повтора

Если POST с Idempotency-Key получил отказ 4xx (кроме 429), повтор с тем же ключом вернёт тот же отказ, не выполняя запрос заново. Исправили данные (добавили дату рождения, выбрали другую смену) — отправляйте с новым ключом. Подробно — в Повтор запроса.

Коды API

Запрос не разобран

`code`	Статус	Когда	Что делать
`bad_request`	400	Неверный JSON или параметр адреса	Проверить, что тело — правильный JSON, параметры — нужного вида
`invalid_input`	422	Поле тела не того вида, не заполнено или незнакомо (имя — в `message`)	Исправить имя или значение поля
`too_large`	413	Тело запроса больше 1 МБ	Разбить на несколько запросов
`method_not_allowed`	405	Метод не поддерживается по этому адресу	Проверить метод
`not_found`	404	Записи нет или она не вашего отдела; неизвестный адрес	Проверить номер и адрес

Списки и параметры

`code`	Статус	Когда	Что делать
`bad_limit`	400	`limit` вне допустимых границ	Обычно 1–200 (у ленты событий 1–500, у сверки 1–5000)
`bad_cursor`	400	Неверный курсор	Начать список заново без `cursor`
`bad_period`	400	Начало периода позже конца	Поменять даты местами
`bad_after`	400	`after` — не номер события или больше последнего	Передать сохранённый номер события; в начале — `0`
`bad_time`	400	Время не в формате RFC 3339	Например `2027-05-14T00:00:00Z`
`bad_status`	400	Неверный фильтр `status`	`active` или `cancelled`
`bad_payment_state`	400	Неверный фильтр `payment_state`	`awaiting`, `secured` или `unpaid`

Данные брони, семьи, ребёнка

`code`	Статус	Когда	Что делать
`birth_date_required`	400	Нет даты рождения ребёнка. Обязательна при оформлении и при смене ФИО или телефона в брони без даты	Спросить дату у родителя (почему — в Бронь и оплата)
`empty_name`	400	Пустое ФИО ребёнка или родителя	Заполнить ФИО
`bad_phone`	400	Телефон родителя не разобран	Казахстанский номер: `8 701 000 00 01` или `+7 701 000 00 01`
`bad_payer_phone`	400	Телефон плательщика не разобран	То же
`unknown_city`	400	Города нет в справочнике (оформление)	Взять номер из справочника городов лагеря
`bad_city`	400	Города нет в справочнике (правка семьи)	То же
`unknown_transfer_point`	400	Точки посадки нет в справочнике	Взять `transfer_point_id` из `transfer_prices` смены
`transfer_not_offered`	400	Из этой точки на смену не возят, или трансфер нужен, а точка не указана	Выбрать точку из `transfer_prices` смены
`bad_children`	400	В оформлении семьи не 1–10 детей	Разбить на несколько запросов
`unknown_booking`	400	Бронь в `together_with` / `booking_ids` не найдена среди ваших	Проверить номера: только ваши брони
`reason_required`	400	Не указана причина отмены	Передать `reason`
`bad_external_id`	400	`external_id` пуст или длиннее 255 знаков	Исправить номер
`duplicate_external_id`	400	Один `external_id` дважды в одном запросе (оформление семьи)	Свой номер каждому ребёнку
`external_id_taken`	409	`external_id` уже у другой вашей записи (в `message` — её номер)	Скорее всего, бронь уже оформлена — прочитать её по `external_id`
`bad_metadata`	400	Метки не по правилам: больше 20 пар, длинный ключ или значение, вложенный объект	Ключ до 40 знаков, значение до 500, без вложенности
`bad_partner_manager`	400	`partner_manager` длиннее 200 знаков	Сократить
`bad_if_match`	400	`If-Match` — не `version` записи	Передать `version` как есть
`version_mismatch`	412	Запись изменили после вашего чтения	Перечитать запись и повторить
`edit_conflict`	409	Бронь изменилась прямо во время правки	Перечитать бронь и повторить
`contacts_hidden`	403	Ребёнка ведёт другой отдел: контакты семьи не правятся	Телефоны меняет отдел, который ведёт ребёнка
`forbidden`	403	Недостаточно прав для действия	Действие доступно только лагерю
`blacklisted`	403	Оформить ребёнка нельзя (запрет лагеря; причина не сообщается)	Обратиться в лагерь
`duplicate_child`	409	Ребёнок уже записан на эту смену (возможно, другим отделом)	Если это ошибка — обратиться в лагерь
`quota_exhausted`	409	Места вашего отдела на смене закончились	Другая смена, или попросить лагерь добавить мест
`voucher_head_only`	403	Путёвку выпускает и отмечает отправленной руководитель отдела или лагерь	Попросить руководителя отдела

Счета Kaspi

`code`	Статус	Когда	Что делать
`bad_kind`	400	`kind` счёта — не `min`/`full`/`amount`	Исправить `kind`
`bad_amount`	400	Сумма не по шаблону, или `amount` передан без `kind: amount`	Сумма строкой: `"50000"` или `"50000.00"`
`min_already_paid`	409	`kind: min`, а минимальный платёж уже внесён	Выставить `full` или `amount`
`invoice_not_live`	409	Счёт уже закрыт — отменять нечего	Перечитать счёт
`invoice_mismatch`	409	По брони разбирается расхождение суммы счёта (при отмене такого счёта — `403`)	Ждать решения лагеря

Ключ и доступ

`code`	Статус	Когда	Что делать
`unauthorized`	401	Нет ключа, опечатка, ключ отозван или истёк	Проверить заголовок `Authorization: Bearer …`; новый ключ — у лагеря
`scope_missing`	403	У ключа нет нужного права (какого — в `message`)	Попросить право у администратора лагеря
`https_required`	403	Запрос по `http://` — ключ отозван	Исправить адрес на `https://`, получить новый ключ
`key_in_url`	400	Ключ в адресе запроса — ключ отозван	Передавать ключ только в заголовке, получить новый ключ
`ip_not_allowed`	403	Запрос не с разрешённого адреса	Сообщить лагерю адрес сервера

Повтор запроса и лимиты

`code`	Статус	Когда	Что делать
`idempotency_key_required`	400	Нет заголовка `Idempotency-Key`	Добавить заголовок
`idempotency_key_too_long`	400	`Idempotency-Key` длиннее 255 знаков	UUID (36 знаков) подходит
`idempotency_mismatch`	422	Этот ключ уже использован с другим телом	Новое действие — новый ключ
`rate_limited`	429	Превышен лимит	Ждать `Retry-After` секунд
`timeout`	503	Сервер не ответил за 30 секунд	Повторить с тем же `Idempotency-Key`: начатое действие доводится до конца
`internal`	500	Внутренняя ошибка сервера	Повторить позже с тем же ключом; если не проходит — в лагерь с `request_id`

Вебхуки

`code`	Статус	Когда	Что делать
`bad_url`	400	Адрес вебхука не принят (не `https`, внутренний, с логином, с `#`, длиннее 2000 знаков)	Причина — в `message`
`bad_event_type`	400	Незнакомый тип события в подписке	Проверить по списку в Событиях
`too_many_webhooks`	409	Уже 5 действующих вебхуков	Отключить ненужный (`DELETE /webhooks/{id}`)
`secret_unavailable`	409	Секрет вебхука недоступен	Сменить секрет (`rotate-secret`)
`webhooks_unavailable`	503	Вебхуки временно недоступны	Повторить позже

Служебные коды

main_department_only (403), too_many_keys (400), bad_job (400) относятся к служебным разделам лагеря. Ключу отдела продаж они не встречаются.

Правила лагеря

Кроме кодов самого API, оформление, правка и счета возвращают коды правил лагеря — те же, что видит менеджер в CRM лагеря:

`code`	Статус	Когда
`sales_closed`	409	Продажи на смену закрыты
`shift_not_open`	409	Продажи на смену ещё не открыты (или смена уже не в продаже)
`no_quota`	409	Вашему отделу не выделена квота на смену
`birth_date_implausible`	400	На дату заезда ребёнку меньше 3 или больше 19 лет — проверьте дату рождения
`bad_birth_date`	400	Дата рождения в будущем
`transfer_point_required`	400	`needs_transfer: true`, а точка посадки не указана
`discount_over_max`	400	Скидка больше `max_discount` смены
`bad_discount`	400	Скидка отрицательная или больше стоимости
`bad_invoice`	400	`invoice` при оформлении — не `min`/`full`/`none`
`too_many_bookings`	400	В «вместе» больше 50 броней
`already_cancelled`	409	Бронь уже отменена
`already_checked_in`	409	Ребёнок уже заехал — бронь не отменить
`not_cancelled`	409	Восстановить можно только отменённую бронь
`same_shift`	409	Перенос на ту же смену
`shift_started`	409	Перенос на уже начавшуюся смену
`booking_cancelled`	409	Счёт по отменённой брони не выставляется
`invoice_live`	409	У брони уже есть неоплаченный счёт
`invoice_paid`	409	Оплаченный счёт не отменяется
`amount_over_debt`	400 / 409	Сумма счёта больше остатка по брони
`fractional_amount`	400	Сумма счёта с тиынами — только целые тенге
`nothing_to_pay`	400	Остаток по брони — ноль
`amount_too_big`	400	Сумма счёта подозрительно велика (лишний ноль?)
`family_shared`	403	Общая семья: её общие данные не правятся (см. Ваша база)
`phone_taken`	409	Второй номер уже записан за другой семьёй

Список пополняется

Новые коды могут появиться в любой момент. Незнакомый код обрабатывайте по коду ответа HTTP: 4xx — показать менеджеру message и не повторять тот же запрос; 5xx — повторить позже с тем же Idempotency-Key.

Править страницу

Last modified on November 5, 2026

Вебхуки Повтор запроса