Каталог кодов ошибок ApiPay: HTTP-статусы, значения поля error, стабильные error_code и асинхронные ошибки Kaspi. У каждого кода — постоянный якорь #код: поле doc_url в ответе API ведёт прямо сюда.
Ошибки приходят в нескольких формах — не путайте их между собой:
400, 401, 429 …) — общий класс ошибки, присутствует всегда.error в теле ответа — конкретная причина синхронной ошибки. Историческая
особенность бэкенда: часть значений — машинные коды в snake_case
(organization_required, kaspi_session_not_configured), а часть — английские фразы
целиком (Organization not found or not verified, Invoice cannot be cancelled).
Поэтому форматы и различаются. Не сравнивайте текст error в коде.error_message — человекочитаемый текст асинхронной ошибки Kaspi (счёт создан
со статусом processing и позже перешёл в error). Фиксированных кодов у Kaspi нет.error_code (новое) — стабильный snake_case-код из фиксированного каталога.
Стройте switch-логику по нему, а не по тексту error/error_message.В колонке «Код» ниже значения сгруппированы по тому, где именно они появляются.
| Код | HTTP | Что это и что делать |
|---|---|---|
400 # | 400 | Bad Request — некорректный запрос или недопустимое состояние. Точная причина — в поле message или error |
401 # | 401 | Unauthorized — API-ключ отсутствует, неверен, истёк или не привязан к организации; либо аккаунт деактивирован |
403 # | 403 | Forbidden — организация заморожена (suspended) или не верифицирована для рабочего режима |
tariff_inactive # | 403 | Нет действующей подписки на ApiPay — оплатите тариф в кабинете. Закрывает все платные операции: создание, отмену и возврат счёта, чеки, изменяющий каталог, создание, изменение и возобновление подписок, проверку номера клиента. Грейса нет — блокировка сразу после expires_at (это поле приходит в теле ответа; null, если тариф не оформлялся). Чтение (GET), оплата тарифа, настройки, подключение кассира, а также приостановка и отмена подписок продолжают работать. В песочнице тариф не требуется |
404 # | 404 | Not Found — ресурс не найден или принадлежит другой организации |
422 # | 422 | Validation Error — ошибка валидации полей; детали в объекте errors |
429 # | 429 | Too Many Requests — превышен общий лимит Public API (200 запросов/мин на API-ключ); смотрите заголовок Retry-After. Отдельно: POST /clients/check ограничен 60 запросами/мин и 10 000 запросами/сутки на API-ключ, а POST /invoices/qr — 60 QR/мин на организацию (на этом 429 заголовка Retry-After нет) |
500 # | 500 | Server Error — внутренняя ошибка сервера |
502 # | 502 | Bad Gateway — ошибка на стороне Kaspi API |
503 # | 503 | Service Unavailable — сессия Kaspi недействительна или истекла |
| Код | HTTP | Что это и что делать |
|---|---|---|
organization_required # | 400 | Организация не подключена — создайте sandbox-организацию для тестов или подключите кассира Kaspi |
Organization not found or not verified # | 400 | Рабочий режим: организация не верифицирована. Дождитесь верификации или тестируйте в песочнице |
kaspi_session_not_configured # | 400 | Кассир Kaspi не подключён. Подключите его в кабинете (Настройки → Авторизация Kaspi) или через поддержку (WhatsApp +7 708 516 74 89) |
kaspi_session_invalid # | 503 | Сессия кассира Kaspi истекла или сброшена. Переподключите кассира — запросите новый SMS-код |
connection_ambiguous # | 422 | У организации несколько активных касс, основная не выбрана — передайте kaspi_connection_id |
sandbox_invoice_limit # | 400 | Достигнут лимит тестовых счетов (500 на организацию) — очистите песочницу в кабинете |
duplicate_idempotency_key # | 409 | Идемпотентность: активный счёт с таким external_order_id_idempotency уже существует — повторный POST /invoices с тем же ключом не создаёт дубликат (в ответе invoice_id и status существующего счёта). Перевыставление возможно, только если предыдущий счёт с этим external_order_id_idempotency находится в статусе expired, cancelled или error |
| Код | HTTP | Что это и что делать |
|---|---|---|
qr_rate_limit # | 429 | Слишком много QR-запросов для организации (лимит 60/мин) — подождите минуту. Заголовок Retry-After на этом 429 не возвращается (в отличие от общего лимита Public API 200/мин) |
qr_render_failed # | 500 | Не удалось сформировать изображение QR-кода — повторите запрос позже |
kaspi_error # | 502 | Kaspi API вернул ошибку при создании QR-токена — повторите позже |
| Код | HTTP | Что это и что делать |
|---|---|---|
Invoice cannot be cancelled # | 400 | Отменить можно только счёт в статусе pending или processing |
Invoice is not refundable # | 400 | Возврат возможен только по оплаченному счёту, ещё не возвращённому полностью |
Refund amount exceeds available amount # | 400 | Сумма возврата больше доступной — смотрите available_for_refund в GET /invoices/{id} |
| Код | HTTP | Что это и что делать |
|---|---|---|
status=error # | — | Счёт создан (201, статус processing), но Kaspi не смог его обработать — статус сменился на error. Причина текстом в поле error_message (GET /invoices/{id}). У Kaspi нет фиксированных кодов — текст приходит как есть |
error_message: номер не в Kaspi # | — | «Этот номер телефона не зарегистрирован в Kaspi. Укажите номер с установленным приложением Kaspi.» — у клиента нет приложения Kaspi; попросите другой номер |
error_message: сбой Kaspi # | — | «Ошибка обработки платежа. Обратитесь в поддержку» или «Не удалось обработать счёт после нескольких попыток» — временный сбой Kaspi; повторите создание счёта позже |
| Код | HTTP | Что это и что делать |
|---|---|---|
error_code (новое поле) # | — | Стабильный snake_case-код ошибки из фиксированного каталога (31 значение). Присутствует в JSON-ответах об ошибках и в webhook-объектах invoice (для status=error) и refund (для status=failed). Поля message/error сохранены без изменений. Определяйте тип ошибки по error_code, текст — для показа пользователю. У каждого кода ниже указана «Доставка» — приходит ли он асинхронно (в webhook) или синхронно (HTTP-ответ с кодом) |
network_unavailable # | — | Сервис временно недоступен (сбой сети/Kaspi). Можно повторить позже. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
session_transient # | — | Временные проблемы авторизации Kaspi. Можно повторить попытку. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
client_not_found # | — | Номер телефона не зарегистрирован в Kaspi. Не повторяемая — попросите другой номер. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
kaspi_throttled # | — | Kaspi ограничил частоту запросов. Повторите через 2–3 минуты. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
refund_window_expired # | — | Срок возврата истёк или возврат уже сделан (часто для refund status=failed). Доставка: async — приходит в invoice.refunded (refund.error_code) |
invoice_already_paid # | — | Счёт уже оплачен. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
invoice_already_cancelled # | — | Счёт уже отменён. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
invoice_not_found_in_kaspi # | — | Счёт не найден в Kaspi. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
organization_not_configured # | — | Организация не настроена (нет рабочей привязки Kaspi). Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
unknown_error # | — | Непредвиденная ошибка обработки — обратитесь в поддержку. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
qr_render_failed # | 500 | Не удалось сформировать изображение QR-кода — повторите запрос. Доставка: sync HTTP 500 + async (webhook invoice.status_changed, status=error) |
kaspi_session_invalid # | 503 | Сессия кассира Kaspi истекла или сброшена — переподключите кассира. Доставка: sync HTTP 503 + async (webhook invoice.status_changed, status=error) |
kaspi_session_unavailable # | 503 | Не удалось проверить сессию Kaspi — попробуйте позже. Доставка: sync HTTP 503 |
manager_throttled # | 429 | Слишком много операций — попробуйте позже. Доставка: sync HTTP 429 |
whatsapp_otp_throttled # | 429 | Слишком частые запросы кода WhatsApp — попробуйте позже. Доставка: sync HTTP 429 |
whatsapp_gateway_error # | 500 | Не удалось отправить код WhatsApp — попробуйте ещё раз. Доставка: sync HTTP 500 |
subscription_payment_failed # | 502 | Не удалось создать счёт для оплаты подписки — попробуйте позже. Доставка: sync HTTP 502 |
kaspi_error # | 502 | Kaspi API вернул ошибку — повторите позже. Текст message содержит конкретную причину от Kaspi. Доставка: sync HTTP 502 + async (для QR-счетов: webhook invoice.status_changed, status=error) |
trial_daily_limit # | 429 | Антифрод/триал: на пробном тарифе превышен дневной лимит создания счетов (50 счетов/сутки). Дождитесь следующего дня или оформите подписку. Доставка: sync HTTP 429 + заголовок Retry-After |
outstanding_recipient_limit # | 429 | Антифрод: слишком много неоплаченных (outstanding) счетов на одного получателя. Дождитесь оплаты или истечения ранее выставленных счетов. Доставка: sync HTTP 429 + заголовок Retry-After |
outstanding_org_limit # | 429 | Антифрод: слишком много неоплаченных (outstanding) счетов по организации в целом. Дождитесь оплаты или истечения ранее выставленных счетов. Доставка: sync HTTP 429 + заголовок Retry-After |
recipient_fanout_exceeded # | 429 | Антифрод: превышен темп рассылки счетов по разным получателям (fan-out). Снизьте частоту создания счетов на разные номера. Доставка: sync HTTP 429 + заголовок Retry-After |
content_rejected # | 422 | Антифрод: содержимое счёта (например текст описания) отклонено проверкой. Исправьте текст и повторите. Доставка: sync HTTP 422 |
sandbox_simulated_error # | — | Симулированная ошибка в песочнице: POST /invoices/{id}/simulate-status со status=error присваивает счёту этот error_code (с опциональным error_message до 255 символов) и шлёт вебхук invoice.status_changed как при реальной ошибке. Только sandbox (в проде simulate-status недоступен). Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
cart_items_mismatch # | — | Зарезервирован — сейчас не используется бэкендом (такие случаи приходят как kaspi_error). Доставка: — |
image_upload_failed # | — | Зарезервирован — сейчас не используется бэкендом. Доставка: — |
catalog_item_not_found # | — | Зарезервирован — сейчас не используется бэкендом. Доставка: — |
| Код | HTTP | Что это и что делать |
|---|---|---|
kaspi_session_expired # | 400 | Сессия Kaspi мерчанта истекла — нужна переавторизация кассира Kaspi. Доставка: sync HTTP 400 |
kaspi_throttled # | 429 | Kaspi троттлит сессию при сканировании. Повторить после паузы (тело retry_after_seconds, заголовок Retry-After). Circuit-breaker: ~90 с сразу отдаёт 429 без обращения к Kaspi. Доставка: sync HTTP 429. Примечание: отличается от async error_code kaspi_throttled по счетам |
kaspi_scan_unavailable # | 503 | Нацкаталог Kaspi временно недоступен — повторить позже. Доставка: sync HTTP 503 |
| Код | HTTP | Что это и что делать |
|---|---|---|
kyc_daily_limit_reached # | 429 | Молодая организация: пока анкета о бизнесе не одобрена, доступен 1 реальный счёт в сутки (окно Asia/Almaty; счета в песочнице не считаются). Чтобы снять лимит — заполните короткую анкету «Расскажите о бизнесе» в кабинете (/business-profile), одобрение обычно за 1 рабочий день. Не повторяйте запрос до сброса. Доставка: sync HTTP 429 (meta.reset_at — когда лимит сбросится, meta.kyc_status — текущий статус) |
kyc_rejected # | 403 | Приём платежей недоступен по итогам проверки бизнеса (статус организации blocked). Не повторяемая — напишите в поддержку, если считаете это ошибкой. Доставка: sync HTTP 403 при создании счёта (POST /invoices, POST /invoices/qr) |
webhook_url_requires_domain # | 422 | Адрес webhook должен быть на вашем домене — IP-адреса не принимаются. Действует для ещё не одобренных организаций в рабочем режиме; в песочнице правило мягче. Укажите публичный HTTPS-адрес на домене. Доставка: sync HTTP 422 при сохранении webhook-URL |
webhook_url_tunnel_forbidden # | 422 | Туннели (ngrok и подобные) нельзя использовать для рабочих webhook — они временны и отключатся, уведомления перестанут приходить. Укажите адрес на вашем домене. Действует для ещё не одобренных организаций в рабочем режиме; в песочнице туннель для локального теста допустим. Доставка: sync HTTP 422 при сохранении webhook-URL |
| Код | HTTP | Что это и что делать |
|---|---|---|
fiscal_receipts_disabled # | 403 | Выбивание чеков отключено для боевых организаций (фича включается постепенно). В песочнице чеки работают всегда — обкатайте интеграцию там. Не повторяемая. Доставка: sync HTTP 403 |
not_sandbox # | 403 | Поле simulate прислано боевой организацией — форсировать исход чека можно только в песочнице. Чек не создан. Уберите simulate из тела запроса. Доставка: sync HTTP 403 (POST /receipts) |
kaspi_session_not_configured # | 409 | К организации не привязан кассир Kaspi Pay — выбить чек не через кого. Подключите кассира в кабинете (Настройки → Подключение кассира). Доставка: sync HTTP 409 |
duplicate_client_operation_id # | 409 | Чек с таким client_operation_id уже выбивался — второй раз он не пробьётся (идемпотентность). В теле ответа приходит receipt_id существующего чека: опросите его через GET /receipts/{id}. Повтор после failed разрешён, но с НОВЫМ ключом. Доставка: sync HTTP 409 |
connection_ambiguous # | 422 | К организации привязано несколько кассиров — непонятно, через какого выбивать чек. Передайте kaspi_connection_id явно. Доставка: sync HTTP 422 |
receipt_preview_unavailable # | 503 | Предпросмотр чека временно недоступен (POST /receipts/preview). Повторяемая — попробуйте позже; на выбивание самого чека не влияет. Доставка: sync HTTP 503 |
receipt_not_found # | 404 | Чек не найден или принадлежит другой организации. Доставка: sync HTTP 404 (GET /receipts/{id}) |
shift_closed # | — | Смена на кассе закрыта — чек выбить нельзя. Откройте смену в приложении Kaspi Pos и повторите с новым client_operation_id. В песочнице воспроизводится через simulate. Доставка: async, status=failed (GET /receipts/{id}, вебхук receipt.failed) |
item_not_fiscal # | — | В чеке есть позиция, не зарегистрированная фискально: у товара должны быть и штрихкод (barcode), и НТИН Нацкаталога (ntin). Дозаполните НТИН в каталоге (PATCH /catalog/{id}) — позиция станет фискальной. Позиции без НТИН удобно найти через GET /catalog?without_ntin=true. Правило одинаково в бою и в песочнице. Доставка: async, status=failed |
rfo_missing # | — | У кассира не настроен фискальный регистратор (РФО) — Kaspi не может зарегистрировать чек. Проверьте настройки кассы в Kaspi Pos. Доставка: async, status=failed |
receipt_kaspi_error # | — | Kaspi отклонил выбивание чека; подробности — в поле error_message чека. Повтор возможен с НОВЫМ client_operation_id. В песочнице воспроизводится через simulate. Доставка: async, status=failed |
receipt_dispatch_error # | — | Не удалось отправить чек в Kaspi (сеть или временный сбой). Повторяемая — попробуйте ещё раз с новым client_operation_id. Доставка: async, status=failed |