Полная таблица лимитов
Каждая строка самодостаточна — можно цитировать по отдельности. Все числа — значения по умолчанию боевого режима.
API-запросы
| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
Запросов на API-ключ (X-API-Key) |
200 в минуту | HTTP 429, повтор через Retry-After |
см. «Что делать при 429» |
| Запросов из кабинета (SPA-сессия) | 300 в минуту | HTTP 429 | — |
| Эндпоинты входа (авторизация) | прогрессивно 5 → 2 → 1 в минуту | HTTP 429, растущая пауза | Вход в кабинет |
Проверка номера POST /clients/check |
60/мин на ключ; 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 |
Жизненный цикл счёта |
Описание счёта (description) |
≤500 символов | ошибка валидации 422 | Создать счёт |
Жизнь QR-счёта (qr_expires_at) |
~5 минут (точный момент истечения определяет Kaspi) | статус expired |
QR-счёт: TTL и лимиты |
| Описание QR-счёта | ≤100 символов | ошибка валидации 422 | — |
| Частота создания QR-счетов | лимит есть, ответ 429 qr_rate_limit |
HTTP 429 | — |
Ключ идемпотентности (external_order_id_idempotency) |
≤191 символ, уникален в организации | HTTP 409 duplicate_idempotency_key |
Идемпотентность |
Скидка на позицию/чек (discount_percentage) |
1–99% (только с cart_items) |
ошибка валидации | Счёт с корзиной |
Размер страницы списка (per_page) |
1–100 | обрезка до границы | — |
| Неоплаченные счета на один номер / организацию | защитный лимит (точное число не публикуется) | HTTP 429 + Retry-After, slug outstanding_recipient_limit / outstanding_org_limit |
дождаться оплаты или отмены прежних |
| Уникальные получатели в день (молодые организации) | защитный лимит (точное число не публикуется) | HTTP 429, slug recipient_fanout_exceeded |
обратиться в поддержку |
| Молодая орг до одобрения анкеты о бизнесе (рабочий режим) | 1 реальный счёт/сутки (окно Asia/Almaty; песочница не считается) | HTTP 429, slug kyc_daily_limit_reached (meta.reset_at) |
заполнить анкету /business-profile, одобрение ~1 рабочий день — лимит снимется сам |
Возвраты
| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Окно возврата | ~14 дней с оплаты | отказ, slug refund_window_expired |
Возвраты через API |
| Попыток обработки возврата | до 3 (автоматически) | вебхук invoice.refunded со статусом failed |
после failed можно создать новый возврат |
| Частичный возврат | по count (целые штуки) или amount (сумма) — ровно одно из двух |
ошибка валидации | статуса refunded у счёта нет |
Подписки
| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
Сумма подписки (amount) |
100 – 1 000 000 ₸ | ошибка «Минимальная сумма подписки — 100 тенге» | Подписки 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 — оплатите тариф |
Тестовый период |
| Тариф Старт | 10 000 ₸/мес, до 30 счетов/день | мягкий лимит: блокировки нет, менеджер предупредит | Тарифы и комиссия |
| Тариф Бизнес | 25 000 ₸/мес, до 100 счетов/день | мягкий лимит: блокировки нет | — |
| Тариф Про | 60 000 ₸/мес, 100–300 счетов/день | — | — |
| Больше 300 счетов/день | договорная цена | напишите нам — обсудим условия | — |
Песочница и кабинет
| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Тестовых счетов в песочнице | ≤500 на организацию | новые не создаются | Песочница и рабочий режим |
| Тест-организаций (партнёр) | ≤20 на партнёра | новые не создаются | — |
| Менеджеров кабинета | ≤5 на организацию | новое приглашение отклоняется | — |
| API-ключей на организацию | без лимита (уникально только имя ключа) | — | Раздельная отчётность |
| Экспорт счетов (CSV/XLSX/PDF) | ≤10 000 строк | обрезка | — |
| Каталог: создание | до 100 товаров за запрос | — | — |
| Каталог: загрузка изображения | jpeg/png/webp ≤2 МБ | ошибка image_upload_failed |
— |
| Каталог: сканирование штрихкодов | 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 с. Так же устроены наши собственные ретраи вебхуков (10 → 30 → 60 → 90 → 120 → 300 с и далее). - Не опрашивайте статусы поллингом.
GET /invoices/{id}разрешает 1000/мин, но это не повод его крутить — подключите вебхуки, и статусы придут сами, без единого лишнего запроса.
Как лимиты зависят от тарифа
От тарифа зависит один лимит — дневное число создаваемых счетов (daily_limit):
- Триал (3 дня): 50 счетов/день.
- Старт (10 000 ₸/мес): до 30 счетов/день.
- Бизнес (25 000 ₸/мес): до 100 счетов/день.
- Про (60 000 ₸/мес): 100–300 счетов/день.
- Больше 300 счетов/день: договорная цена — напишите нам.
На платных тарифах дневной лимит мягкий: при превышении блокировки нет — менеджер предупредит и предложит тариф выше. Считаются только счета, созданные через API (у которых есть api_key_id). Внешние счета, подтянутые синхронизацией из приложения Kaspi, в дневной лимит не входят. Все прочие лимиты из таблиц выше от тарифа не зависят — они одинаковы для Старт, Бизнес и Про.
Частые ошибки
- Крутить
GET /invoices/{id}в цикле вместо вебхуков. Формально 1000/мин хватает, но это лишняя нагрузка и риск 429 на пиках. Вебхук приходит сам. - Повторять запрос сразу после 429, игнорируя
Retry-After. Блокировка только удлиняется. - Считать, что дневной лимит счетов растёт с числом кассиров. Он привязан к тарифу организации, а не к числу подключений.
- Слать описание счёта длиннее лимита. Для счёта по номеру потолок 500 символов, для QR-счёта — 100. Превышение — ошибка 422 ещё до Kaspi.
- Ожидать возврат после ~14 дней. Окно закрывается — придёт
refund_window_expired.
Частые вопросы
Какой лимит запросов в минуту у ApiPay?
200 запросов в минуту на один API-ключ. Кабинет (SPA-сессия) — 300/мин. Отдельно ограничена проверка номера /clients/check: 60/мин на ключ и 10/мин на один номер кассира.
Сколько живёт счёт и QR-счёт?
Счёт по номеру живёт в Kaspi 24 часа, затем становится expired. QR-счёт живёт около 5 минут — точный момент истечения определяет Kaspi.
Что значит HTTP 429 и что делать?
Превышен лимит частоты запросов. Прочитайте заголовок Retry-After (число секунд до повтора) и подождите. При /clients/check частая причина — лимит 10/мин на один номер кассира.
Сколько попыток даётся вебхуку?
В боевом режиме — 11 попыток с нарастающим backoff (10, 30, 60, 90, 120, 300, 600, 900, 1800, 3600 сек). После 5 неудач подряд канал ставится на паузу (circuit breaker), после 50 — полностью отключается.
Сколько счетов в день можно создавать?
Зависит от тарифа: триал — 50/день, Старт — до 30, Бизнес — до 100, Про — 100–300; больше 300 в день — договорная цена. Считаются только счета, созданные через API.
Есть ли лимит на число API-ключей?
Нет. Ключей у организации может быть сколько угодно, ограничена только уникальность имени ключа. Менеджеров кабинета — до 5.
Берёте ли вы или Kaspi процент с оплат?
ApiPay процент не берёт — только фиксированная подписка по тарифу. Kaspi удерживает свою обычную комиссию за приём платежа (~0,95%): со счёта 2 000 ₸ на ваш Kaspi-счёт поступит ~1 981 ₸. Эта комиссия Kaspi действует и без ApiPay.