Ошибки и ограничения #

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

Все ошибки — один и тот же вид: HTTP-код и текст.

{ "message": "Торговая точка не найдена" }

Текст рассчитан на человека и годится для лога или сообщения оператору. Логику не стройте на его содержимом — опирайтесь на HTTP-код.

Коды ответов #

Типовые ошибки #

Валидация #

{ "message": "Поле Торговая точка обязательно для заполнения." }
{ "message": "Поле Торговая точка должно быть корректным UUID." }
{ "message": "Поле Тип заказа должно быть целым числом." }

Возвращается первая найденная ошибка, не список. Исправили — можете получить сообщение о следующей.

Точка и меню #

Товары #

Все три проверяются и в POST /orders/calculate — вызывайте его перед заказом, и пользователь увидит проблему раньше.

Отчёты #

Заказ #

Ограничения #

Лимиты считаются на ключ: если один ваш сервер работает с ключами нескольких брендов, у каждого ключа свой счётчик.

При превышении лимита — 429 с заголовком Retry-After (секунды до сброса счётчика):

{ "message": "Превышен лимит запросов. Повторите через 23 с", "retry_after": 23 }

Ждите retry_after секунд, а не повторяйте сразу: повтор до сброса счётчика тоже получит 429. Если заголовка нет — экспоненциальная задержка 1 с, 2 с, 4 с, 8 с.

Повторные попытки #

Можно повторять безопасно: все GET-методы, POST /orders/calculate и POST /reports/olap — они ничего не меняют.

POST /orders — повторяйте только с тем же external_id. Тогда повтор вернёт существующий заказ, а не создаст второй. Без external_id повтор создаст дубль.

Что повторять: 429, 500, таймауты, обрывы соединения. Что не повторять: 400, 404, 409 — они не изменятся сами; сначала исправьте запрос.

Изоляция данных #

Ключ видит только данные своего бренда. Обращение к точке, меню или заказу другого заведения вернёт 404 — не 403, чтобы по коду ответа нельзя было выяснить, существует ли объект.

Поддержка #

Не сходятся суммы, не приходят заказы, непонятная ошибка — обращайтесь в поддержку Mison. Приложите:

• external_id и order_id заказа;
• point_id;
• время запроса с часовым поясом;
• тело запроса и полученный ответ.