Ошибки

Формат

{
  "error": {
    "code": "limit_exceeded",
    "message": "not enough tickets in some zones",
    "details": {
      "zones": [{ "id": 11, "requested": 4, "available": 1 }]
    }
  },
  "request_id": "9f2c4e7a1b3d5f60718293a4b5c6d7e8"
}

Обрабатывайте ошибки по error.code. Текст message предназначен для логов и может меняться.

Коды ошибок

Запрос и авторизация

HTTP	code	Когда
400	invalid_json	Тело запроса — не валидный JSON или поля неверного типа
400	validation_error	Не передан partner_order_id при поиске заказа; неверный формат дат или период в отчёте
400	invalid_pagination	limit или page не положительное целое
400	invalid_event_id, invalid_event_item_id	ID в пути не положительное целое
400	invalid_category_id, invalid_child_map_id	Параметр запроса не положительное целое
401	unauthorized	Неверный, отключённый или истёкший ключ
403	forbidden	IP-адрес не входит в whitelist ключа
404	not_found	Мероприятие, сеанс, заказ или путь не найдены

Бизнес-логика заказов

HTTP	code	Когда	details
422	validation_error	Неверный состав заказа или возврата	зависит от причины
422	event_item_not_available	Сеанс не существует или не продаётся	—
409	seat_unavailable	Одно или несколько мест заняты или недоступны	seats: ID мест
409	limit_exceeded	Не хватает билетов в зоне, категории или сеансе; превышен лимит на заказ	см. ниже
409	order_expired	Бронь истекла или до её окончания меньше 10 секунд	—
409	order_not_held	Операция недоступна в текущем статусе заказа	status: текущий статус
409	refund_not_allowed	Сеанс начался, билеты использованы или возвращать нечего	ticket_ids: использованные билеты

Сервер

HTTP	code	Когда
500	internal_error	Внутренняя ошибка. Повторите запрос позже; если ошибка сохраняется, напишите в поддержку с request_id
503	db_unavailable	Только /ready: база данных недоступна

Детали ошибок

seat_unavailable

{ "details": { "seats": [101, 102] } }

Места, которые нельзя забронировать. Обновите схему зала и предложите покупателю выбрать другие места.

limit_exceeded

В зависимости от причины details содержит одно из полей:

Поле	Причина
limit_per_order	Превышен лимит билетов на один заказ: 50 или лимит сеанса
zones	Не хватает билетов в зонах: массив { id, requested, available }
prices	Не хватает билетов в ценовых категориях: массив { id, requested, available }
requested, available	Не хватает билетов в общем лимите сеанса

{ "details": { "limit_per_order": 10 } }

{ "details": { "prices": [{ "id": 4179, "requested": 5, "available": 2 }] } }

validation_error при создании заказа

message	Причина
partner_order_id is required	Не передан partner_order_id
partner_order_id must be at most 255 characters	Слишком длинный partner_order_id
event_item_id is required	Не передан event_item_id
customer.email is invalid	Некорректный email покупателя
customer fields must be at most 255 characters	Слишком длинное поле покупателя
seats must contain positive seat ids	В seats есть 0
seat N is listed twice	Место указано дважды
zones must contain zone_id and a positive quantity	Неверный элемент zones
prices must contain price_id and a positive quantity	Неверный элемент prices
order must contain at least one seat, zone or price	Пустой заказ
this event item has no seating plan, order tickets by prices	Для сеанса type = 6 переданы seats или zones
prices can only be ordered for event items without seats, use seats or zones	Для сеанса со схемой переданы prices
this price category is sold by whole rows only	Категория продаётся целым рядом. В details.required_seats — все места ряда

order_not_held

{ "details": { "status": "expired" } }

Текущий статус заказа, из-за которого операция невозможна.

Рекомендации по повторам

Ошибка	Повторять?
Сетевая ошибка, таймаут, 500, 503	Да, с паузой. Для POST /orders повтор безопасен благодаря partner_order_id
401, 403	Нет — проверьте ключ и IP
400, 422	Нет — исправьте запрос
409 seat_unavailable, limit_exceeded	Нет — обновите схему и предложите покупателю другие билеты (с новым partner_order_id)
409 order_expired	Нет — создайте новый заказ