> Источник: https://apipay.kz/guides/limity-i-kvoty-apipay · Обновлено: 2026-08-26 · 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 повторами**, после **5** подряд неудач канал ставится на паузу; возврат возможен **~14 дней**, до **3 попыток**; дневной лимит счетов зависит от тарифа (Старт — до 30, Бизнес — до 100, Про — до 300, Про Макс — до 600; больше 600 — договорные условия), в триале — **50 счетов/день**. При превышении лимита запросов приходит **HTTP 429** с заголовком `Retry-After`. Ниже — все лимиты одной таблицей.

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

Все числа — значения по умолчанию боевого режима.

### 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 не бьёт; лучше вебхуки |
| Тест вебхука `POST /api-keys/{id}/test-webhook` | 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 | до 05.09.2026 длиннее 60 принимается, но покупатель увидит только первые 60; с 05.09.2026 — `422 description_too_long` (организациям, зарегистрированным с 26.08.2026, — уже сейчас) | [Создать счёт](/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-счетов | 60 запросов в минуту на организацию | 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`) | ошибка валидации | [Счёт с корзиной](/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` | обратиться в поддержку |
| Молодая орг до одобрения анкеты о бизнесе (рабочий режим) | 1 реальный счёт/сутки (окно Asia/Almaty; песочница не считается); пока `kyc_deadline` в `GET /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) |
| День списания (`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) |
| Тариф Старт | до 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-ключей на организацию | без лимита (уникально только имя ключа) | — | [Раздельная отчётность](/guides/razdelnaya-otchetnost-po-tochkam) |
| Экспорт счетов (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** означает, что вы превысили лимит частоты запросов. Порядок действий:

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

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

От тарифа зависит **один** лимит — дневное число создаваемых счетов (`daily_limit`), значения в таблице выше. Считаются только счета, созданные **через API** (у которых есть `api_key_id`): счета из кабинета, печатный лист и песочница в лимит не входят.

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

Когда включается ограничение, как читать `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 и что делать?**
Превышен лимит частоты запросов. Прочитайте заголовок `Retry-After` (число секунд до повтора) и подождите. При `/clients/check` частая причина — лимит 10/мин на один номер кассира.

**Сколько попыток даётся вебхуку?**
В боевом режиме — 11 попыток с нарастающим backoff (10, 30, 60, 90, 120, 300, 600, 900, 1800, 3600 сек). После 5 неудач подряд канал ставится на паузу (circuit breaker), после 50 — полностью отключается.

---

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