Пачка счетов Kaspi массово отменяется или падает — почему?

Сначала проверьте

Какой статус у «отменённых» счетов — error или cancelled? От темпа выставления счёт уходит в error. cancelled означает другое: отмену покупателем, вашу отмену через API или кабинет либо отказной терминальный статус от Kaspi.
Какой error_code в вебхуках? kaspi_throttled — ограничение частоты со стороны Kaspi.
Насколько плотно выставляете? Риск возникает, когда счета уходят один за другим без пауз с одного кассира; ровный поток с паузами проходит нормально.

Ветки диагностики

Признак	Причина	Что сделать	Подробнее
Хвост пачки уходит в `error` с `kaspi_throttled`	Kaspi ограничил частоту запросов кассира	Разнести выставление во времени, выставлять ровным потоком с паузами и перевыставить эти счета заново	— (решение в этой статье)
Счета висят в `processing` дольше нескольких минут	Включён «Режим накопления счетов» либо выставление не завершилось — сервис финализирует счёт в `error` с вебхуком	Не пересоздавать: ждите вебхук	«Жизненный цикл счёта»
Счета в `cancelled`, а не в `error`	Это не темп: отмена покупателем, ваша отмена или отказной терминальный статус от Kaspi	Разбирать по конкретным счетам: `GET /invoices/{id}` и раздел «Счета» в кабинете	«Жизненный цикл счёта»
Нужно регулярно выставлять сотни счетов за раз	Цикл из сотни одиночных POST'ов — лишние запросы	`POST /invoices/bulk` — до 100 счетов за запрос	— (ниже в этой статье)

Что происходит при плотном залпе

Счёт, попавший под ограничение частоты Kaspi, финализируется сразу: error, error_code: kaspi_throttled, вебхук. Автоповторов нет — перевыставляете его вы; следующий счёт того же кассира пробует заново с нуля.

Что работает на практике:

Разносите нагрузку: тот же объём в два «окна» (утро/вечер) вместо одного залпа. Сотни счетов в день проходят нормально в пределах дневного лимита вашего тарифа — важно не собирать их в один плотный залп. Про сам лимит и его превышение — «Лимит счетов по тарифу».
Bulk-выставление: POST /invoices/bulk — до 100 счетов одним запросом, лимит 20 запросов/мин, спецификация в документации API. Экономит сетевые обращения; на темп выставления в Kaspi и на риск kaspi_throttled не влияет — каждый счёт выставляется так же, как одиночный.
«Режим накопления счетов» (Настройки → Организация, включает владелец): счета копятся и уходят в Kaspi пачкой раз в заданное окно. Имеет смысл при 100+ оплатах в день; пока режим включён, покупатель сможет оплатить только после отправки пачки, поэтому для розницы «здесь и сейчас» он не подходит.
Идемпотентность (external_order_id_idempotency) — чтобы ваши ретраи не плодили дубли.

Не пересоздавайте processing

Не пересоздавайте счёт, пока он в processing: получатся два живых счёта, и покупатель может оплатить оба.

Если лавину создаёт ваш собственный цикл

Если ваш код в ответ на ошибку немедленно шлёт новые счета — остановите интеграцию целиком: кабинет → Настройки → «Подключение» → удалите API-ключи. Счета мгновенно перестанут выставляться, деньги и созданные счета не пострадают. Удаление необратимо, поэтому полный протокол остановки и восстановления смотрите в «Счета дублируются — как остановить?».

Для вашего ИИ-агента

Смотрите: error_code в вебхуках (kaspi_throttled — счёт финален, нужно перевыставить новым счётом и снизить темп); 429 + Retry-After на API-лимитах; включено ли накопление — GET /account/health → invoicing.accumulating; счета в processing не пересоздавать — читать last_kaspi_error_code/last_kaspi_error_message в GET /invoices/{id}; перевыставление — только по вебхуку invoice.status_changed со status: error.

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

Можно ли выставлять большое количество счетов в день?

Да, в пределах дневного лимита тарифа — см. «Лимит счетов по тарифу». Ограничение частоты со стороны Kaspi зависит не от суточного объёма, а от плотности залпа.

Какая частота выставления безопасна?

Выставляйте ровным потоком с паузами между счетами, а не залпом, и разносите объём на несколько окон в день.