EN
Разделы документации

Ошибки и лимиты

Формат ошибки, все коды с HTTP-статусами, лимиты запросов и размеров и какие запросы стоит повторять.

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

Любая ошибка приходит одним и тем же JSON:

Ответ 409

{
  "error": {
    "code": "sold_out",
    "message": "Билеты этого тарифа закончились",
    "details": {"tariff_id": "0193e0b2-4a7d-7a21-8c44-6e2f9a0b3c71"}
  }
}
  • code не меняется. Пишите логику по нему.
  • message написан по-русски для человека, и текст может меняться. Его можно показать оператору, но разбирать не стоит.
  • details есть не всегда. В нём поле, тариф, место или причина: набор ключей зависит от ошибки.

Коды

КодHTTPКогдаЧто делать
invalid_request400Неверный JSON, поле или параметр. Причина в message, иногда поле в detailsИсправить запрос. Тот же запрос снова не пройдёт
unauthorized401Нет ключа, ключ неверный или отозван, организация приостановленаПроверить ключ
forbidden403Действие доступно только в кабинете: details.reason: "session_only"Сделать это в кабинете
not_found404Нет такого объекта или метода. Объект другой организации или режима тоже не найдётсяПроверить id и режим ключа
event_not_on_sale409Событие не опубликовано, или продажа тарифа и мест ещё открывается после публикацииОпубликовать событие. После публикации подождать несколько секунд
sold_out409Билеты тарифа закончились, details.tariff_idПредложить другой тариф или вернуть деньги
seat_taken409Место уже в резерве у другого заказа или продано, details.seat_id и details.seatПредложить другое место
reservation_expired409Резерв истёк, а свободных билетов уже нетВернуть деньги покупателю
idempotency_conflict409Idempotency-Key занят другим запросом, ещё выполняется или результат неизвестенСм. идемпотентность
limit_exceeded422В заказе больше 20 билетов или больше, чем разрешает тариф на один заказУменьшить заказ или разбить его
rate_limited429Превышен лимит запросовПодождать Retry-After секунд
internal500Сбой на нашей сторонеПовторить с тем же Idempotency-Key

Пока сервис перезапускается, прокси может ответить 502, 503 или 504 без JSON. Повторите такой запрос с тем же Idempotency-Key.

Лимиты

ЧтоСколько
Запросы с одного ключа600 в минуту
Тело JSON1 МБ
Файл мест5 МБ, до 50 000 мест
Файл гостей1 МБ, до 2 000 строк
Обложка5 МБ, до 25 мегапикселей
Билетов в одном заказе20
Резервот 60 до 1 800 секунд, по умолчанию 900
Idempotency-Keyдо 255 символов, хранится 24 часа
Повторное письмо с билетомраз в минуту на билет
Страница спискабилеты до 200, места до 5 000

Лимит запросов считается по календарным минутам. Превышение даёт 429 rate_limited с заголовком Retry-After и details.retry_after_s: сколько секунд осталось до новой минуты.

Какие запросы повторять

  • 429: через Retry-After секунд.
  • 5xx, таймаут и обрыв связи: с тем же Idempotency-Key, с паузой, которая растёт с каждой попыткой (1, 2, 4 секунды…).
  • 400, 401, 403, 404, 422: не повторять, сначала исправить запрос.
  • 409: зависит от кода. sold_out, seat_taken и reservation_expired окончательные. event_not_on_sale сразу после публикации проходит через несколько секунд. Про idempotency_conflict см. идемпотентность.