Лимиты, статусы и ошибки

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

{
  "success": false,
  "error": {
    "code": "REFUND_AMOUNT_MISMATCH",
    "message": "Confirmed amount differs from requested amount"
  }
}

Основные ошибки

HTTP	Код	Что делать
400	INVALID_IDEMPOTENCY_KEY	Исправить формат ключа
401	UNAUTHORIZED, INVALID_CREDENTIALS	Проверить API key и secret
403	INSUFFICIENT_SCOPE	Добавить один из required_scopes
404	NOT_FOUND	Проверить ID, ресторан и владельца объекта
409	REFUND_AMOUNT_MISMATCH	Сверить сумму, не создавать второй возврат
409	REFUND_CONFIRMATION_CONFLICT	Остановить повторы и сверить операцию провайдера
409	PAYMENT_ID_MISMATCH	Не заменять ID исходного платежа
422	ORDER_CANNOT_BE_CANCELLED	Получить актуальный заказ и передать оператору
422	IDEMPOTENCY_KEY_REUSED	Оставить прежнее тело или создать новый ключ для новой операции
429	RATE_LIMIT_EXCEEDED	Ждать Retry-After и повторить тот же запрос
429	DAILY_LIMIT_EXCEEDED	Ждать суточного сброса из meta.reset_at
500/503	—	Повторить с тем же ключом и телом

Ответ при достижении лимита

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Превышен лимит запросов"
  },
  "meta": {
    "retry_after": 37,
    "reset_at": "2026-08-20T15:08:00+05:00"
  }
}

Параметры также передаются в заголовках Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. Всегда ориентируйтесь на фактические заголовки ответа конкретного API-клиента: назначенный лимит может зависеть от его тарифа и настроек.

Профили лимитов

Rate-plan API — техническая настройка интеграции, а не коммерческий тариф ресторана. При включении интеграции MenuLab назначает подходящий профиль; его можно изменить без выпуска нового ключа.

Профиль	Назначение	Обычные запросы	Короткий burst	Отмена и подтверждение возврата
Sandbox (free)	Разработка и приёмочные тесты	30/мин, 1 000/сутки	5/сек	15/мин, 1 000/сутки
Standard (standard)	Обычный сайт, backend мобильного приложения, CRM	120/мин, 10 000/сутки	20/сек	30/мин, 2 000/сутки
Business (business)	Сеть ресторанов или активный агрегатор	300/мин, 50 000/сутки	50/сек	60/мин, 10 000/сутки
High volume (enterprise)	Крупный агрегатор или высокая нагрузка	1 000/мин, без суточного лимита	100/сек	120/мин, без суточного лимита

Новый production API-клиент автоматически получает профиль Standard. Sandbox назначается тестовому окружению явно, а Business и High volume — только при подтверждённой нагрузке. Индивидуальный минутный лимит меняет только скорость обычных запросов: суточный лимит и критический резерв продолжают действовать.

POST /orders/{id}/cancel и POST /refunds/{id}/confirm используют отдельные минутный и суточный buckets. Исчерпание обычного лимита polling не блокирует корректное завершение отмены или возврата. Критический резерв нельзя использовать для чтения статусов.

burst ограничивает резкий всплеск в пределах одной секунды; минутный и суточный пределы при этом также применяются.

Как не исчерпать лимит

1. Получайте изменения через webhook.
2. Опрашивайте только незавершённые объекты.
3. Для статуса используйте /orders/status, а не полный список заказов.
4. После completed, cancelled, succeeded прекращайте polling.
5. Учитывайте Retry-After, применяйте backoff и jitter.
6. Не запускайте несколько параллельных циклов для одного заказа.

Мобильное приложение должно обращаться к вашему backend, а backend — к MenuLab. X-API-Secret нельзя встраивать в мобильное приложение или браузерный JavaScript. Основной канал статусов — webhook; резервный polling допустим раз в 30–60 секунд только для незавершённых заказов.

Точное текущее потребление видно из X-RateLimit-Remaining. Если production-нагрузка обоснованно выше назначенного лимита, передайте поддержке API client ID, ожидаемый RPS, суточный объём и перечень методов.