Правила запросов и ошибки
Конверт ответа
Успех — данные в data, у списков рядом лежит meta с пагинацией. Ошибка — объект error.
{
"error": {
"code": "seat_taken",
"message": "Часть мест уже занята",
"details": { "unavailable_seats": ["zone-1|zone-1-1-1"] }
},
"request_id": "req_01kz47m06k53xhxy558wgez8hz"
}Разбирайте code, а не текст: message написан для человека и может меняться.
Коды ошибок
| HTTP | code | Что делать |
|---|---|---|
| 401 | unauthenticated | Ключ не передан, отозван или истёк |
| 403 | insufficient_scope | У ключа нет права на метод |
| 403 | ip_not_allowed | Запрос с адреса вне белого списка |
| 404 | not_found | Объекта нет либо он принадлежит другой компании |
| 409 | seat_taken | Места заняли раньше вас — обновите занятость и предложите другие |
| 409 | reservation_expired | Бронь истекла, соберите её заново |
| 422 | validation_failed | Проверьте тело запроса, подробности в details |
| 429 | rate_limited | Превышен лимит, подождите по заголовку Retry-After |
| 500 | server_error | Наша ошибка — повторите позже и пришлите request_id |
Идемпотентность
Каждый запрос, который что-то создаёт или меняет деньги, требует заголовок Idempotency-Key —
произвольную строку, уникальную для этой операции. Если связь оборвалась и вы повторили запрос с тем же ключом,
вернётся тот же результат, а второй заказ не появится.
POST https://api.ctickets.ru/v1/orders
Idempotency-Key: order-2026-08-03-00042Ключ живёт сутки. Тот же ключ с другим телом запроса — ошибка: так ловится подмена операции.
Лимиты
Лимит считается по приложению, а не по адресу: несколько ваших серверов делят общий бюджет.
По умолчанию 120 запросов в минуту, организатор может поднять лимит в кабинете.
В ответ приходят X-RateLimit-Limit и X-RateLimit-Remaining.
Пагинация и фильтры
pageиper_page— постранично.- Фильтры передаются как
filter.status=published,filter.city_id=5. updated_sinceв каталоге — забирать только изменившееся, а не весь список.
Время и деньги
- Время — ISO 8601 с зоной:
2026-08-03T19:33:01+03:00. - Деньги — целое число копеек и валюта отдельно.