Обновлено: 25.08.2026
Ошибки и лимиты
Ошибки возвращаются с соответствующим HTTP-статусом и телом вида { "error": { "code": "...", "message": "..." } }. Поле code стабильно между версиями API — ориентируйтесь на него в коде, а не на текст message, который может меняться и локализоваться.
Коды ошибок
| Статус | Код | Описание |
|---|---|---|
400 | invalid_request | Не хватает обязательного поля или неверный формат. |
401 | unauthenticated | Токен не передан или недействителен. |
403 | forbidden | Токену не хватает прав на это действие. |
404 | not_found | Объект с таким ID не найден. |
409 | conflict | Действие конфликтует с текущим состоянием объекта — например, повторная оплата уже оплаченного заказа. |
422 | insufficient_points | Недостаточно баллов лояльности для списания. |
429 | rate_limited | Превышен лимит запросов — см. заголовок Retry-After. |
Лимиты запросов
Лимит — 120 запросов в минуту на токен, отдельно считается для песочницы и боевой среды. Текущее состояние лимита отражено в заголовках ответа на каждый запрос.
| Заголовок | Значение |
|---|---|
X-RateLimit-Limit | Лимит запросов в минуту |
X-RateLimit-Remaining | Сколько запросов осталось в текущем окне |
Retry-After | Через сколько секунд можно повторить запрос после 429 |
Полезно знать
- При параллельной интеграции нескольких сервисов используйте отдельные токены на каждый — так лимит не делится на всех и проще найти источник всплеска запросов.
- Массовые операции (например, начисление баллов всей аудитории) выносите в задачи экспорта или обсуждайте отдельный лимит с поддержкой — не гоняйте цикл по 429.