> Источник: https://apipay.kz/guides/limity-i-kvoty-apipay · Обновлено: 2026-10-24 · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay.

# Лимиты и квоты ApiPay: полный справочник

**TL;DR.** Ключевые лимиты ApiPay: **200 запросов в минуту** на API-ключ; счёт по номеру живёт **24 часа**, его описание — **до 60 символов**: Kaspi показывает покупателю только первые 60, остальное не показывает; QR-счёт даёт на скан **меньше трёх минут** — точный момент всегда берите из `qr_expires_at`, константу в коде не зашивайте; описание QR-счёта — **до 100 символов**; проверка клиента (`/clients/check`) — **60/мин и 10 000/сутки на ключ** и **10/мин на один номер кассира**; для событий счетов в рабочем режиме — до **11 попыток доставки** (первая и 10 повторов), после серии неудач подряд на ключе — пауза, при затянувшихся отказах — отключение до успешной проверки (починить адрес и нажать «Проверить уведомления» в кабинете); возврат возможен **~14 дней**, до **3 попыток**; дневной лимит счетов зависит от тарифа (Старт — до 30, Бизнес — до 100, Про — до 300, Про Макс — до 600; больше 600 — договорные условия), в триале — **50 счетов/день**. При **HTTP 429** сначала разбирайте код ограничения и соблюдайте `Retry-After`, если он есть: не каждый 429 содержит время повтора. Ниже — все лимиты одной таблицей.

## Полная таблица лимитов

Все числа — значения по умолчанию боевого режима. Коды ответов и формат ошибок — в [документации API](/docs).

### API-запросы

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Запросов на API-ключ (`X-API-Key`) | 200 в минуту | HTTP 429, повтор через `Retry-After` | см. «Что делать при 429» |
| Запросов из кабинета (SPA-сессия) | 300 в минуту | HTTP 429 | — |
| Эндпоинты входа (авторизация) | частота ограничена; при повторных неудачах пауза растёт | HTTP 429, повтор по `Retry-After` | [Вход в кабинет](/guides/vhod-v-kabinet-apipay) |
| Проверка номера `POST /clients/check` | 60/мин **и 10 000/сутки** на ключ; 200/мин и 20 000/сутки на организацию; **10/мин на один номер кассира** | HTTP 429 `scope=kaspi_throttle` | 10/мин на кассира — техническое ограничение на стороне обработки |
| Поллинг `GET /invoices/{id}` | 1000 в минуту | HTTP 429 | читает из БД/кэша, в Kaspi не бьёт; общий лимит 200/мин не тратит |
| Тест вебхука (кнопка «Проверить уведомления» в кабинете) | 5 в минуту | HTTP 429 | [Настройка вебхуков](/guides/nastroyka-webhookov-apipay) |

### Счета и QR

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Жизнь счёта по номеру в Kaspi | 24 часа | по истечении статус `expired` | [Жизненный цикл счёта](/guides/zhiznennyy-tsikl-scheta) |
| Сумма счёта по номеру телефона | только целые тенге, от `1`; проверяется и `amount`, и итог корзины после скидок | HTTP 422 `amount_must_be_whole_tenge` | нужны копейки — выставляйте через `POST /invoices/qr` (без скидки) |
| Отмена QR-счёта | не поддерживается | HTTP 409 `qr_cancel_unsupported`, статус не меняется | [QR-счёт: TTL и лимиты](/guides/qr-schet-ttl-i-limity) |
| Описание счёта (`description`) | ≤60 символов — Kaspi показывает покупателю только первые 60 | длиннее 60 — `422 description_too_long` | [Создать счёт](/guides/kak-sozdat-schet-kaspi-po-nomeru) |
| Окно на скан QR-счёта (`qr_expires_at`) | меньше трёх минут — длительность задаёт Kaspi, считайте её из поля, а не из константы | статус `expired`; оплата, начатая до конца окна, завершается и позже | [QR-счёт: TTL и лимиты](/guides/qr-schet-ttl-i-limity) |
| Картинка QR (`qr_image_url`) | живёт до `qr_expires_at` + 60 секунд | дальше HTTP 404 — перевыпустите QR, а не перезагружайте картинку | — |
| Описание QR-счёта | ≤100 символов | ошибка валидации 422 | — |
| Частота создания QR-счетов | 200 запросов в минуту на организацию | HTTP 429 `qr_rate_limit`, без `Retry-After` — повторить примерно через минуту | [QR-счёт: окно на скан и лимиты](/guides/qr-schet-ttl-i-limity) |
| Ключ идемпотентности (`external_order_id_idempotency`) | ≤191 символ, уникален в организации | HTTP 409 `duplicate_idempotency_key` | [Идемпотентность](/guides/kak-sozdat-schet-kaspi-po-nomeru) |
| Скидка на чек (`discount_percentage`) | 1–99% (только с `cart_items`); на QR-счёте и статическом QR — только целый процент | ошибка валидации 422; на QR — ещё `qr_discount_unsupported` (цена позиции в тиынах или скидка обнуляет позицию) | [Счёт с корзиной](/guides/scheta-s-korzinoy-cart-items-ofd) |
| Размер страницы списка (`per_page`) | счета, возвраты, чеки, логи — 1–100; `GET /catalog` — до 200 (по умолчанию 50) | у счетов и логов — ошибка валидации 422; у каталога значение обрезается до 200 | [Каталог и корзина](/guides/katalog-korzina-nackatalog) |
| Неоплаченные счета на один номер / организацию | защитный лимит (точное число не публикуется) | HTTP 429 + `Retry-After`, slug `outstanding_recipient_limit` / `outstanding_org_limit` | дождаться оплаты или отмены прежних |
| Уникальные получатели в день (молодые организации) | защитный лимит (точное число не публикуется) | HTTP 429, slug `recipient_fanout_exceeded` | обратиться в поддержку |
| Молодая орг до одобрения анкеты о бизнесе (рабочий режим) | боевые счета не выставляются, `meta.limit` = `0` (песочница не затронута); пока `kyc_deadline` в `GET /api/users/me` в будущем — ограничение не действует | HTTP 429, slug `kyc_daily_limit_reached` (`meta.reset_at`) | [Анкета о бизнесе](/guides/anketa-o-biznese-i-limit) |
| Массовое выставление счетов (`POST /invoices/bulk`) | до 100 счетов в одном запросе, 20 запросов в минуту | больше 100 в пачке — ошибка валидации 422; чаще 20 запросов/мин — HTTP 429 + `Retry-After` | разбивайте рассылку на пачки по 100 и выдерживайте паузу между запросами |

### Возвраты

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Окно возврата | ~14 дней с оплаты | отказ, slug `refund_window_expired` | [Возвраты через API](/guides/vozvraty-kaspi-cherez-api) |
| Попыток обработки возврата | до 3 (автоматически) | вебхук `invoice.refunded` со статусом `failed` | после `failed` можно создать новый возврат |
| Частичный возврат | по `count` (целые штуки) или `amount` (сумма) — ровно одно из двух | ошибка валидации | статуса `refunded` у счёта нет |

### Подписки

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Сумма подписки (`amount`) | 100 – 1 000 000 ₸, **только целые тенге** | ошибка «Минимальная сумма подписки — 100 тенге»; дробная сумма принимается при создании, но каждое списание уходит в `error` с `amount_must_be_whole_tenge` | [Подписки ApiPay](/guides/podpiski-apipay) |
| Итог корзины подписки (`cart_items`) | 100 – 1 000 000 ₸, **только целые тенге**, по текущим ценам каталога | `422` с `error_code: cart_total_out_of_range` или `cart_total_not_whole_tenge`, текст в `errors.cart_items` | [Подписки ApiPay](/guides/podpiski-apipay) |
| День списания (`billing_day`) | 1–28 | ошибка валидации | — |
| Счетов за период при неоплате (`max_retry_attempts`) | 1–10 (по умолчанию 3); действует только без `bill_until_paid: true` | далее — grace-период; вместе с `bill_until_paid: true` — `422` | [Подписки ApiPay](/guides/podpiski-apipay) |
| Интервал повтора (`retry_interval_hours`) | 1–168 ч (по умолчанию 24) | — | — |
| Grace-период (`grace_period_days`) | 1–30 дней (по умолчанию 3); только без `bill_until_paid: true` | по истечении — `subscription.expired`; вернуть в работу — `POST /subscriptions/{id}/resume` | [Подписки ApiPay](/guides/podpiski-apipay) |
| Период биллинга (`billing_period`) | daily / weekly / biweekly / monthly / quarterly / yearly | — | — |

### Вебхуки

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Попыток доставки `invoice.status_changed` | до 11 в рабочем режиме, до 3 в песочнице | первая попытка включена; автоматических повторов после исчерпания нет | [Настройка вебхуков](/guides/nastroyka-webhookov-apipay) |
| Попыток доставки `invoice.refunded`, `subscription.*` | до 11 в обоих режимах | первая + до 10 повторов | — |
| Попыток доставки `invoice.qr_scanned`, `qr_refund.*` | до 11 в рабочем режиме, до 3 в песочнице | отдельные короткие интервалы | — |
| Попыток доставки `catalog.*`, `receipt.*` | до 3 в обоих режимах | первая + до 2 повторов | — |
| Backoff `invoice.status_changed` в рабочем режиме и `invoice.refunded`/`subscription.*` в обоих режимах, сек | 10, 30, 60, 90, 120, 300, 600, 900, 1800, 3600 | не распространяется на другие события | — |
| Получателей на событие | до 2 (ключ-создатель + org-default) | лишние не добавляются | — |
| Пауза доставки (счётчик неудач подряд на API-ключе, сбрасывается успехом) | после серии неудач — пауза, время снятия в `GET /webhook-logs/delivery-state`; при затянувшихся отказах — отключение | вебхуки счетов, возвратов и `qr_refund.*` не отправляются и не копятся; подписки, чеки, касса и каталог уходят как обычно | [Почему вебхуки не приходят](/guides/webhook-ne-prihodit) |
| Ручной повтор вебхука | cooldown 10 сек, только статус `failed` | — | — |
| Таймаут на ответ вашего endpoint | 3 с соединение + 5 с ответ; отвечать 2xx до 5 секунд | попытка считается неудачной | — |

### Тарифы и триал

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Триал | 3 дня, **50 счетов/день** | HTTP 429, slug `trial_daily_limit` — оплатите тариф | [Тестовый период](/guides/testovyy-period) |
| Тариф Старт | до 30 счетов/день | разовое превышение не блокирует; при систематическом превышении — HTTP 429, slug `tariff_limit_reached` | [Лимит счетов по тарифу](/guides/limit-schetov-po-tarifu) |
| Тариф Бизнес | до 100 счетов/день | то же | [Тарифы и комиссия](/guides/tarify-i-komissiya-apipay) |
| Тариф Про | до 300 счетов/день | то же | — |
| Тариф Про Макс | до 600 счетов/день | то же | — |
| Помесячный подсчёт (по запросу) | бюджет на 30 дней = дневной лимит × 30 | HTTP 429 `tariff_limit_reached`, `meta.mode: monthly` | — |
| Больше 600 счетов/день | договорные условия | напишите нам | — |

### Песочница и кабинет

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Тестовых счетов в песочнице | ≤1000 на организацию | новые не создаются | [Песочница и рабочий режим](/guides/pesochnitsa-i-rabochiy-rezhim) |
| Тест-организаций (партнёр) | ≤20 на партнёра | новые не создаются | — |
| Сотрудников кабинета (менеджеры и разработчики) | ≤10 на организацию | новое приглашение отклоняется | — |
| API-ключей на организацию | без лимита (уникально только имя ключа) | — | [API-ключ и вебхук-секрет](/guides/api-klyuch-i-webhook-secret) |
| Экспорт счетов (CSV/XLSX/PDF) | ≤10 000 строк | обрезка | — |
| Каталог: создание | до 100 товаров за запрос | — | — |
| Каталог: загрузка изображения | только JPEG/PNG, ≤6 МБ, стороны 64…6000 px, площадь ≤12 Мпикс; 60/мин; 2000/сутки на пару ключ + организация и 6000/сутки на ключ (дедуп по MD5) | >6 МБ — HTTP 413 `file_too_large`; не тот формат или габариты — HTTP 422 | — |
| Каталог: сканирование штрихкодов | 30/мин, 2000/день | HTTP 429 / breaker ~90 с | — |

## Что делать при 429?

**HTTP 429** может означать лимит частоты, квоту счетов или защитное ограничение. Порядок действий:

1. **Сначала прочитайте `error_code`/`error` и `scope`.** Действие зависит от причины, а не только от HTTP-кода. При `kyc_daily_limit_reached` с `meta.limit = 0` нужно одобрение анкеты — смена суточного окна не поможет. При `recipient_fanout_exceeded` нужен разбор через поддержку, времени повтора в ответе нет.
2. **Прочитайте заголовок `Retry-After`**, если он есть: это число секунд до повтора, раньше повторять не нужно. `meta.reset_at` есть только у отдельных ограничений; не требуйте это поле от каждого 429. `scope=kaspi_throttle` при `/clients/check` означает, что упёрлись в лимит **10 запросов/мин на один номер кассира**: соблюдайте паузу, разнесите проверки во времени и проверяйте номер только перед выставлением счёта конкретному клиенту.
3. **Backoff для временного ограничения частоты.** Если `Retry-After` нет — повторяйте с ростом паузы только при подтверждённом временном лимите и учитывайте его окно. Для `qr_rate_limit` окно минутное: первая пауза примерно минуту, без цикла через 1–2 секунды. Не применяйте этот совет к KYC или другому ограничению, требующему действия человека.
4. **Проверьте квоту или неоплаченные счета.** Для `tariff_limit_reached` смотрите `meta.reset_at` либо повышение тарифа; для `outstanding_*` дождитесь оплаты или отмены прежних счетов.
5. **Опрашивайте статус с паузой.** `GET /invoices/{id}` — 1000/мин на ключ: раз в 3–5 секунд, пока покупатель на экране оплаты, дальше реже. Много счетов или нужен мгновенный отклик — [подключите вебхуки](/guides/nastroyka-webhookov-apipay), опрос оставьте страховкой.

## Как лимиты зависят от тарифа?

От тарифа зависит **один** лимит — дневное число создаваемых счетов (`daily_limit`), значения в таблице выше. Считаются только счета, созданные **через API** (у которых есть `api_key_id`), в любом статусе — в том числе истёкшие без оплаты: счета из кабинета, статический QR, созданный в кабинете, и песочница в лимит не входят. У статического QR, созданного через API, место занимает каждый счёт, выпущенный после нажатия покупателем «Оплатить в Kaspi» — подробнее в статье «[Лимит счетов по тарифу](/guides/limit-schetov-po-tarifu)».

Все прочие лимиты из таблиц выше **от тарифа не зависят** — они одинаковы для Старт, Бизнес, Про и Про Макс.

Когда включается ограничение, как читать `429 tariff_limit_reached` и как перейти на помесячный подсчёт — в статье [Лимит счетов по тарифу](/guides/limit-schetov-po-tarifu).

## Частые вопросы

**Какой лимит запросов в минуту у ApiPay?**
200 запросов в минуту на один API-ключ. Кабинет (SPA-сессия) — 300/мин. Отдельно ограничена проверка номера `/clients/check`: 60/мин и 10 000/сутки на ключ, 200/мин и 20 000/сутки на организацию, 10/мин на один номер кассира.

**Что значит HTTP 429 и что делать?**
Сначала разберите `error_code`/`error`: 429 может означать частоту, квоту или защитное ограничение. Если есть `Retry-After`, соблюдайте паузу. У `qr_rate_limit` заголовка нет — повторите примерно через минуту; при KYC с `meta.limit = 0` нужно одобрение анкеты, ждать нового окна бесполезно.

**Сколько попыток даётся вебхуку?**
Зависит от события. У `invoice.status_changed`, `invoice.qr_scanned` и `qr_refund.*` — до 11 попыток в рабочем режиме и до 3 в песочнице; у `invoice.refunded` и `subscription.*` — до 11 в обоих; у `catalog.*` и `receipt.*` — до 3 в обоих. Первая попытка включена в число. Интервалы различаются — см. [настройку вебхуков](/guides/nastroyka-webhookov-apipay). После серии неудач подряд на API-ключе отправка встаёт на паузу, при затянувшихся отказах — отключается; успешная доставка сбрасывает счётчик.

---

ApiPay — независимый сервис и не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки их правообладателя.
База знаний: https://apipay.kz/guides