Коротко
Если пришёл 429, сначала посмотрите на поле error — за ним стоят две совершенно разные ситуации.
tariff_limit_reached— закончился месячный лимит счетов вашего тарифа. Это обычная бизнес-ситуация: повышаете тариф или ждёте нового месяца.tariff_daily_burst— сработала суточная защита. Это не бизнес-лимит, а признак того, что в вашем коде есть цикл. Повышать тариф здесь неправильно, сначала нужно разобраться с кодом.
Счета песочницы в лимит не входят, так что работу с ключом qp_test_… можно продолжать.
Симптом → причина → решение
| Симптом | Код ошибки | Причина | Решение |
|---|---|---|---|
| В середине месяца счета встали, объём обычный | tariff_limit_reached | Кончился месячный лимит | Повысьте тариф или дождитесь нового месяца |
| Начало месяца, всё встало за несколько минут | tariff_daily_burst | Цикл в коде, повторная отправка | Остановите код и найдите причину |
| Одному покупателю ушли десятки одинаковых счетов | tariff_daily_burst | Логика ретраев неидемпотентна | Добавьте Idempotency-Key |
| Быстро встало на пробном периоде | tariff_daily_burst | На пробном 50 счетов в сутки | Тестируйте в песочнице |
| 429, но код другой | rate_limited | Частота запросов, а не лимит | Смотрите заголовок Retry-After |
Как различить
Поле error в теле ответа — единственный надёжный признак. HTTP-статус в обоих случаях 429, поэтому решение по одному коду статуса принимать нельзя.
В кабинете в разделе Тариф видно, где сейчас месячный счётчик. Если до лимита далеко, а 429 приходит — значит это суточная защита.
Месячный счётчик считается по календарному месяцу по времени Алматы. То есть он обнуляется первого числа, а не в день регистрации.
tariff_limit_reached — месячный лимит
Это плановая ситуация: бизнес вырос, лимит тарифа закончился.
| Тариф | Счетов в месяц |
|---|---|
| Старт | 800 |
| Бизнес | 4 000 |
| Про | 15 000 |
| Партнёрский | без ограничения |
Что делать:
- Зайдите в Кабинет → Тариф и посмотрите текущий счётчик.
- Повысьте тариф. Новый лимит вступает в силу сразу, счета снова пойдут.
- Или дождитесь нового месяца — счётчик обнулится.
- Продолжайте работу в песочнице — тестовые счета в лимит не входят, разработка не останавливается.
Как выбрать тариф: Какой тариф выбрать, полный справочник: Тарифы и лимиты.
Как не попасть: планируйте смену тарифа, когда месячный счётчик доходит примерно до 80 процентов. В момент, когда лимит кончился, продажи встают — и обычно это происходит в самый неудобный день.
tariff_daily_burst — суточная защита
Суточное число — не бизнес-лимит. Оно существует, чтобы защитить вас от зациклившейся интеграции: если код по ошибке отправляет одно и то же снова и снова, счета и обращения к Kaspi не должны расти лавиной.
| Тариф | Суточная защита |
|---|---|
| Пробный | 50 |
| Старт | 200 |
| Бизнес | 1 500 |
| Про | 5 000 |
Если пришла эта ошибка, первое действие — не повышать тариф, а проверить код. Чаще всего дело в одном из этого:
- Ретраи без ограничения. При неудачном запросе код повторяет его бесконечно.
- Обработчик вебхука создаёт новый счёт. В ответ на событие создаётся ещё счёт, получается бесконечная цепочка.
- Форма отправляется дважды. Кнопка не блокируется, покупатель жмёт два-три раза.
- Фоновая задача наложилась сама на себя. Предыдущий запуск не закончился, а стартовал новый.
- Тестовый скрипт запустили боевым ключом.
Что делать:
- Остановите интеграцию. Пока цикл работает, мусорные счета копятся каждую минуту.
- Посмотрите счета за последний час. Если в разделе Счета повторяются одинаковые суммы и описания — цикл найден.
- Добавьте
Idempotency-Key. С тем же ключом повторный запрос не создаёт новый счёт, а возвращает прежний. Подробнее: Идемпотентность. - Отмените мусорные счета, особенно если они успели уйти покупателям.
- Ограничьте ретраи: максимум 3-5 попыток с растущей паузой.
Если счета уже задублировались, срочные действия описаны отдельно: Счета дублируются.
Не путайте лимит с частотой запросов
Есть третий вид 429 — rate_limited или request_rate_limited. Он относится не к количеству счетов, а к частоте обращений: вы запрашиваете слишком часто. Здесь нужно прочитать заголовок Retry-After и повторить через указанное время. Подробнее: Ограничения частоты запросов.
| Код | О чём | Первое действие |
|---|---|---|
tariff_limit_reached | Счета за месяц | Повысить тариф |
tariff_daily_burst | Счета за сутки | Проверить код |
rate_limited | Частота запросов | Подождать по Retry-After |
tariff_inactive | Тариф не оплачен или пробный кончился | Кабинет → Тариф |
Вопросы и ответы
Если повысить тариф, вырастет ли суточная защита? Да, у каждого тарифа своё суточное число. Но повышать тариф в ответ на tariff_daily_burst — значит прятать причину, а не устранять её.
Входят ли счета песочницы в лимит? Нет. Счета, созданные ключом qp_test_…, не влияют ни на месячный лимит, ни на суточную защиту. Поэтому тестирование интеграции лимит не съедает.
Что будет с уже созданными счетами, когда лимит достигнут? Ничего. Открытые счета оплачиваются, вебхуки приходят, возвраты работают. Останавливается только создание новых счетов.
Когда обнуляется месячный счётчик? В начале календарного месяца по времени Алматы. Не в день вашей регистрации.
Какой лимит на пробном периоде? 7 дней, 50 счетов в сутки. Пробный период начинается с первого боевого счёта, а не с даты регистрации. Песочница пробный период не запускает: Пробный период.
Считаются ли отменённые и истёкшие счета? Счётчик работает по созданным счетам. Поэтому зациклившаяся интеграция съедает лимит, даже если ни один счёт не оплачен — ещё один довод в пользу идемпотентности.