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

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

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

## Коротко

| Что | Значение |
|---|---|
| Запросов в минуту на API-ключ | 200 |
| Жизнь счёта по номеру | 24 часа |
| Жизнь QR-счёта | 5 минут |
| Описание счёта / QR-счёта | ≤500 / ≤100 символов |
| Проверка номера `/clients/check` | 60/мин на ключ, 10/мин на кассира |
| Ретраи вебхука | 11 (prod) / 3 (sandbox) |
| Окно возврата | ~14 дней, до 3 попыток |
| Дневной лимит счетов (триал) | 50/день |
| Молодая орг до одобрения анкеты о бизнесе | 1 реальный счёт/сутки (песочница без лимита) |
| Ответ при превышении | HTTP 429 + `Retry-After` |

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

Каждая строка самодостаточна — можно цитировать по отдельности. Все числа — значения по умолчанию боевого режима.

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

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Запросов на API-ключ (`X-API-Key`) | 200 в минуту | HTTP 429, повтор через `Retry-After` | см. «Что делать при 429» |
| Запросов из кабинета (SPA-сессия) | 300 в минуту | HTTP 429 | — |
| Эндпоинты входа (авторизация) | прогрессивно 5 → 2 → 1 в минуту | HTTP 429, растущая пауза | [Вход в кабинет](/guides/vhod-v-kabinet-apipay) |
| Проверка номера `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 | [Настройка вебхуков](/guides/nastroyka-webhookov-apipay) |

### Счета и QR

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Жизнь счёта по номеру в Kaspi | 24 часа | по истечении статус `expired` | [Жизненный цикл счёта](/guides/zhiznennyy-tsikl-scheta) |
| Описание счёта (`description`) | ≤500 символов | ошибка валидации 422 | [Создать счёт](/guides/kak-sozdat-schet-kaspi-po-nomeru) |
| Жизнь QR-счёта (`qr_expires_at`) | ~5 минут (точный момент истечения определяет Kaspi) | статус `expired` | [QR-счёт: TTL и лимиты](/guides/qr-schet-ttl-i-limity) |
| Описание QR-счёта | ≤100 символов | ошибка валидации 422 | — |
| Частота создания QR-счетов | лимит есть, ответ `429 qr_rate_limit` | HTTP 429 | — |
| Ключ идемпотентности (`external_order_id_idempotency`) | ≤191 символ, уникален в организации | HTTP 409 `duplicate_idempotency_key` | [Идемпотентность](/guides/kak-sozdat-schet-kaspi-po-nomeru) |
| Скидка на позицию/чек (`discount_percentage`) | 1–99% (только с `cart_items`) | ошибка валидации | [Счёт с корзиной](/guides/scheta-s-korzinoy-cart-items-ofd) |
| Размер страницы списка (`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](/guides/anketa-o-biznese-i-limit), одобрение ~1 рабочий день — лимит снимется сам |

### Возвраты

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Окно возврата | ~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 тенге» | [Подписки ApiPay](/guides/podpiski-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 | далее запись в лог, авто-повтора нет | [Настройка вебхуков](/guides/nastroyka-webhookov-apipay) |
| Попыток доставки (песочница, 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 → полное отключение | вебхуки не отправляются до сброса | [Почему вебхуки не приходят](/guides/webhook-ne-prihodit) |
| Ручной повтор вебхука | cooldown 10 сек, только статус `failed` | — | — |
| Таймаут на ответ вашего endpoint | 3 с соединение + 5 с ответ; отвечать 2xx до 5 секунд | попытка считается неудачной | — |

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

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Триал | 3 дня, **50 счетов/день** | HTTP 429, slug `trial_daily_limit` — оплатите тариф | [Тестовый период](/guides/testovyy-period) |
| Тариф Старт | 10 000 ₸/мес, до 30 счетов/день | мягкий лимит: блокировки нет, менеджер предупредит | [Тарифы и комиссия](/guides/tarify-i-komissiya-apipay) |
| Тариф Бизнес | 25 000 ₸/мес, до 100 счетов/день | мягкий лимит: блокировки нет | — |
| Тариф Про | 60 000 ₸/мес, 100–300 счетов/день | — | — |
| Больше 300 счетов/день | договорная цена | напишите нам — обсудим условия | — |

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

| Лимит | Значение | Что при превышении | Подробнее |
|---|---|---|---|
| Тестовых счетов в песочнице | ≤500 на организацию | новые не создаются | [Песочница и рабочий режим](/guides/pesochnitsa-i-rabochiy-rezhim) |
| Тест-организаций (партнёр) | ≤20 на партнёра | новые не создаются | — |
| Менеджеров кабинета | ≤5 на организацию | новое приглашение отклоняется | — |
| API-ключей на организацию | без лимита (уникально только имя ключа) | — | [Раздельная отчётность](/guides/razdelnaya-otchetnost-po-tochkam) |
| Экспорт счетов (CSV/XLSX/PDF) | ≤10 000 строк | обрезка | — |
| Каталог: создание | до 100 товаров за запрос | — | — |
| Каталог: загрузка изображения | jpeg/png/webp ≤2 МБ | ошибка `image_upload_failed` | — |
| Каталог: сканирование штрихкодов | 30/мин, 2000/день | HTTP 429 / breaker ~90 с | — |

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

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

1. **Прочитайте заголовок `Retry-After`** — там число секунд, через которое можно повторить. Не долбите эндпоинт раньше: это только продлевает блокировку.
2. **Смотрите на `scope` в теле ответа.** `scope=kaspi_throttle` при `/clients/check` означает, что упёрлись в лимит **10 запросов/мин на один номер кассира** — это техническое ограничение на стороне обработки. Разнесите проверки во времени; проверяйте номер только перед выставлением счёта конкретному клиенту.
3. **Экспоненциальный backoff.** Если `Retry-After` нет — повторяйте с ростом паузы: 1 с, 2 с, 4 с, 8 с. Так же устроены наши собственные ретраи вебхуков (10 → 30 → 60 → 90 → 120 → 300 с и далее).
4. **Не опрашивайте статусы поллингом.** `GET /invoices/{id}` разрешает 1000/мин, но это не повод его крутить — [подключите вебхуки](/guides/nastroyka-webhookov-apipay), и статусы придут сами, без единого лишнего запроса.

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

От тарифа зависит **один** лимит — дневное число создаваемых счетов (`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.

---

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