Полная таблица лимитов
Все числа — значения по умолчанию боевого режима.
API-запросы
| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
Запросов на API-ключ (X-API-Key) |
200 в минуту | HTTP 429, повтор через Retry-After |
см. «Что делать при 429» |
| Запросов из кабинета (SPA-сессия) | 300 в минуту | HTTP 429 | — |
| Эндпоинты входа (авторизация) | частота ограничена; при повторных неудачах пауза растёт | HTTP 429, повтор по Retry-After |
Вход в кабинет |
Проверка номера POST /clients/check |
60/мин и 10 000/сутки на ключ; 200/мин и 20 000/сутки на организацию; 10/мин на один номер кассира | HTTP 429 scope=kaspi_throttle |
10/мин на кассира — техническое ограничение на стороне обработки |
Поллинг GET /invoices/{id} |
1000 в минуту | HTTP 429 | читает из БД/кэша, в Kaspi не бьёт; лучше вебхуки |
Тест вебхука POST /api-keys/{id}/test-webhook |
5 в минуту | HTTP 429 | Настройка вебхуков |
Счета и QR
| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Жизнь счёта по номеру в Kaspi | 24 часа | по истечении статус expired |
Жизненный цикл счёта |
| Сумма счёта по номеру телефона | только целые тенге, от 1; проверяется и amount, и итог корзины после скидок |
HTTP 422 amount_must_be_whole_tenge |
нужны копейки — выставляйте через POST /invoices/qr |
| Отмена QR-счёта | не поддерживается | HTTP 409 qr_cancel_unsupported, статус не меняется |
QR-счёт: TTL и лимиты |
Описание счёта (description) |
≤60 символов — Kaspi показывает покупателю только первые 60 | до 05.09.2026 длиннее 60 принимается, но покупатель увидит только первые 60; с 05.09.2026 — 422 description_too_long (организациям, зарегистрированным с 26.08.2026, — уже сейчас) |
Создать счёт |
Окно на скан QR-счёта (qr_expires_at) |
меньше трёх минут — длительность задаёт Kaspi, считайте её из поля, а не из константы | статус expired; оплата, начатая до конца окна, завершается и позже |
QR-счёт: TTL и лимиты |
Картинка QR (qr_image_url) |
живёт до qr_expires_at + 60 секунд |
дальше HTTP 404 — перевыпустите QR, а не перезагружайте картинку | — |
| Описание QR-счёта | ≤100 символов | ошибка валидации 422 | — |
| Частота создания QR-счетов | 60 запросов в минуту на организацию | HTTP 429 qr_rate_limit, без Retry-After — повторить примерно через минуту |
QR-счёт: окно на скан и лимиты |
Ключ идемпотентности (external_order_id_idempotency) |
≤191 символ, уникален в организации | HTTP 409 duplicate_idempotency_key |
Идемпотентность |
Скидка на позицию/чек (discount_percentage) |
1–99% (только с cart_items) |
ошибка валидации | Счёт с корзиной |
Размер страницы списка (per_page) |
счета, возвраты, чеки, логи — 1–100; GET /catalog — до 200 (по умолчанию 50) |
у счетов и логов — ошибка валидации 422; у каталога значение обрезается до 200 | Каталог и корзина |
| Неоплаченные счета на один номер / организацию | защитный лимит (точное число не публикуется) | HTTP 429 + Retry-After, slug outstanding_recipient_limit / outstanding_org_limit |
дождаться оплаты или отмены прежних |
| Уникальные получатели в день (молодые организации) | защитный лимит (точное число не публикуется) | HTTP 429, slug recipient_fanout_exceeded |
обратиться в поддержку |
| Молодая орг до одобрения анкеты о бизнесе (рабочий режим) | 1 реальный счёт/сутки (окно Asia/Almaty; песочница не считается); пока kyc_deadline в GET /users/me в будущем — лимит не действует |
HTTP 429, slug kyc_daily_limit_reached (meta.reset_at) |
Анкета о бизнесе |
Массовое выставление счетов (POST /invoices/bulk) |
до 100 счетов в одном запросе, 20 запросов в минуту | больше 100 в пачке — ошибка валидации 422; чаще 20 запросов/мин — HTTP 429 + Retry-After |
разбивайте рассылку на пачки по 100 и выдерживайте паузу между запросами |
Возвраты
| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Окно возврата | ~14 дней с оплаты | отказ, slug refund_window_expired |
Возвраты через API |
| Попыток обработки возврата | до 3 (автоматически) | вебхук invoice.refunded со статусом failed |
после failed можно создать новый возврат |
| Частичный возврат | по count (целые штуки) или amount (сумма) — ровно одно из двух |
ошибка валидации | статуса refunded у счёта нет |
Подписки
| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
Сумма подписки (amount) |
100 – 1 000 000 ₸, только целые тенге | ошибка «Минимальная сумма подписки — 100 тенге»; дробная сумма принимается при создании, но каждое списание уходит в error с amount_must_be_whole_tenge |
Подписки ApiPay |
День списания (billing_day) |
1–28 | ошибка валидации | — |
Попыток при неоплате (max_retry_attempts) |
1–10 (по умолчанию 3) | далее — grace-период | — |
Интервал повтора (retry_interval_hours) |
1–168 ч (по умолчанию 24) | — | — |
Grace-период (grace_period_days) |
1–30 дней (по умолчанию 3) | по истечении — subscription.expired, реактивации нет |
— |
Период биллинга (billing_period) |
daily / weekly / biweekly / monthly / quarterly / yearly | — | — |
Вебхуки
| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Попыток доставки (боевой режим) | 11 | далее запись в лог, авто-повтора нет | Настройка вебхуков |
| Попыток доставки (песочница, invoice) | 3 | — | — |
| Backoff между попытками, сек | 10, 30, 60, 90, 120, 300, 600, 900, 1800, 3600 | — | — |
| Получателей на событие | до 2 (ключ-создатель + org-default) | лишние не добавляются | — |
| Circuit breaker (пауза канала) | ≥5 неудач → 5 мин, ≥10 → 30 мин, ≥20 → 2 ч, ≥50 → полное отключение | вебхуки не отправляются до сброса | Почему вебхуки не приходят |
| Ручной повтор вебхука | cooldown 10 сек, только статус failed |
— | — |
| Таймаут на ответ вашего endpoint | 3 с соединение + 5 с ответ; отвечать 2xx до 5 секунд | попытка считается неудачной | — |
Тарифы и триал
| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Триал | 3 дня, 50 счетов/день | HTTP 429, slug trial_daily_limit — оплатите тариф |
Тестовый период |
| Тариф Старт | до 30 счетов/день | разовое превышение не блокирует; при систематическом превышении — HTTP 429, slug tariff_limit_reached |
Лимит счетов по тарифу |
| Тариф Бизнес | до 100 счетов/день | то же | Тарифы и комиссия |
| Тариф Про | до 300 счетов/день | то же | — |
| Тариф Про Макс | до 600 счетов/день | то же | — |
| Помесячный подсчёт (по запросу) | бюджет на 30 дней = дневной лимит × 30 | HTTP 429 tariff_limit_reached, meta.mode: monthly |
— |
| Больше 600 счетов/день | договорные условия | напишите нам | — |
Песочница и кабинет
| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Тестовых счетов в песочнице | ≤1000 на организацию | новые не создаются | Песочница и рабочий режим |
| Тест-организаций (партнёр) | ≤20 на партнёра | новые не создаются | — |
| Сотрудников кабинета (менеджеры и разработчики) | ≤10 на организацию | новое приглашение отклоняется | — |
| API-ключей на организацию | без лимита (уникально только имя ключа) | — | Раздельная отчётность |
| Экспорт счетов (CSV/XLSX/PDF) | ≤10 000 строк | обрезка | — |
| Каталог: создание | до 100 товаров за запрос | — | — |
| Каталог: загрузка изображения | только JPEG/PNG, ≤6 МБ, стороны 64…6000 px, площадь ≤12 Мпикс; 60/мин и 2000/сутки на ключ (дедуп по MD5) | >6 МБ — HTTP 413 file_too_large; не тот формат или габариты — HTTP 422 |
— |
| Каталог: сканирование штрихкодов | 30/мин, 2000/день | HTTP 429 / breaker ~90 с | — |
Что делать при 429
HTTP 429 означает, что вы превысили лимит частоты запросов. Порядок действий:
- Прочитайте заголовок
Retry-After— там число секунд, через которое можно повторить. Не долбите эндпоинт раньше: это только продлевает блокировку. - Смотрите на
scopeв теле ответа.scope=kaspi_throttleпри/clients/checkозначает, что упёрлись в лимит 10 запросов/мин на один номер кассира. Разнесите проверки во времени; проверяйте номер только перед выставлением счёта конкретному клиенту. - Экспоненциальный backoff. Если
Retry-Afterнет — повторяйте с ростом паузы: 1 с, 2 с, 4 с, 8 с. - Не опрашивайте статусы поллингом.
GET /invoices/{id}разрешает 1000/мин, но это не повод его крутить — подключите вебхуки, и статусы придут сами.
Как лимиты зависят от тарифа
От тарифа зависит один лимит — дневное число создаваемых счетов (daily_limit), значения в таблице выше. Считаются только счета, созданные через API (у которых есть api_key_id): счета из кабинета, печатный лист и песочница в лимит не входят.
Все прочие лимиты из таблиц выше от тарифа не зависят — они одинаковы для Старт, Бизнес, Про и Про Макс.
Когда включается ограничение, как читать 429 tariff_limit_reached и как перейти на помесячный подсчёт — в статье Лимит счетов по тарифу.
Частые вопросы
Какой лимит запросов в минуту у ApiPay?
200 запросов в минуту на один API-ключ. Кабинет (SPA-сессия) — 300/мин. Отдельно ограничена проверка номера /clients/check: 60/мин и 10 000/сутки на ключ, 200/мин и 20 000/сутки на организацию, 10/мин на один номер кассира.
Что значит HTTP 429 и что делать?
Превышен лимит частоты запросов. Прочитайте заголовок Retry-After (число секунд до повтора) и подождите. При /clients/check частая причина — лимит 10/мин на один номер кассира.
Сколько попыток даётся вебхуку?
В боевом режиме — 11 попыток с нарастающим backoff (10, 30, 60, 90, 120, 300, 600, 900, 1800, 3600 сек). После 5 неудач подряд канал ставится на паузу (circuit breaker), после 50 — полностью отключается.