# Каталог ошибок ApiPay

> Источник: https://apipay.kz/errors · Обновлено: 2026-08-26 · apipay.kz
> Постоянные якоря: doc_url в ответе API ведёт на https://apipay.kz/errors#{error_code}.

Ошибки приходят в нескольких формах — не путайте их между собой:

- **HTTP-статус** (`400`, `401`, `429` …) — общий класс ошибки, присутствует всегда.
- **Поле `error`** в теле ответа — конкретная причина синхронной ошибки. Значения бывают
  двух видов: машинные коды в snake_case (`organization_required`,
  `kaspi_session_not_configured`) и английские фразы целиком
  (`Organization not found or not verified`, `Invoice cannot be cancelled`).
  **Не сравнивайте текст `error` в коде** — для ветвления используйте `error_code`.
- **Поле `error_message`** — человекочитаемый текст асинхронной ошибки Kaspi (счёт создан
  со статусом `processing` и позже перешёл в `error`). Фиксированных кодов у Kaspi нет.
- **Поле `error_code`** (новое) — стабильный snake_case-код из фиксированного каталога.
  Стройте switch-логику по нему, а не по тексту `error`/`error_message`.

В колонке «Код» ниже значения сгруппированы по тому, где именно они появляются.

## HTTP-статусы (общие для всех эндпоинтов)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `400` (#400) | 400 | Bad Request — некорректный запрос или недопустимое состояние. Точная причина — в поле message или error |
| `401` (#401) | 401 | Unauthorized — API-ключ отсутствует, неверен, истёк или не привязан к организации; либо аккаунт деактивирован |
| `403` (#403) | 403 | Forbidden — организация заморожена (suspended) или не верифицирована для рабочего режима |
| `tariff_inactive` (#tariff_inactive) | 403 | Нет действующей подписки на ApiPay — оплатите тариф в кабинете. Закрывает все платные операции: создание, отмену и возврат счёта, чеки, изменяющий каталог, создание, изменение и возобновление подписок, проверку номера клиента. Грейса нет — блокировка сразу после expires_at (это поле приходит в теле ответа; null, если тариф не оформлялся). Чтение (GET), оплата тарифа, настройки, подключение кассира, а также приостановка и отмена подписок продолжают работать. В песочнице тариф не требуется |
| `404` (#404) | 404 | Not Found — ресурс не найден или принадлежит другой организации |
| `422` (#422) | 422 | Validation Error — ошибка валидации полей; детали в объекте errors |
| `429` (#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) | 500 | Server Error — внутренняя ошибка сервера |
| `502` (#502) | 502 | Bad Gateway — ошибка на стороне Kaspi API |
| `503` (#503) | 503 | Service Unavailable — сессия Kaspi недействительна или истекла |

## Поле «error» при создании счёта (POST /invoices, /invoices/qr)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `organization_required` (#organization_required) | 400 | Организация не подключена — создайте sandbox-организацию для тестов или подключите кассира Kaspi |
| `Organization not found or not verified` (#organization-not-found-or-not-verified) | 400 | Рабочий режим: организация не верифицирована. Дождитесь верификации или тестируйте в песочнице |
| `kaspi_session_not_configured` (#kaspi_session_not_configured) | 400 | Кассир Kaspi не подключён. Подключите его в кабинете (Настройки → Авторизация Kaspi) или через поддержку (WhatsApp +7 700 307 65 12) |
| `kaspi_session_invalid` (#kaspi_session_invalid) | 503 | Сессия кассира Kaspi истекла или сброшена. Переподключите кассира — запросите новый SMS-код |
| `connection_ambiguous` (#connection_ambiguous) | 422 | У организации несколько активных касс, основная не выбрана — передайте kaspi_connection_id |
| `sandbox_invoice_limit` (#sandbox_invoice_limit) | 400 | Достигнут лимит тестовых счетов (1000 на организацию) — очистите песочницу в кабинете |
| `duplicate_idempotency_key` (#duplicate_idempotency_key) | 409 | Идемпотентность: активный счёт с таким external_order_id_idempotency уже существует — повторный POST /invoices с тем же ключом не создаёт дубликат (в ответе invoice_id и status существующего счёта). Перевыставление возможно, только если предыдущий счёт с этим external_order_id_idempotency находится в статусе expired, cancelled или error |
| `amount_must_be_whole_tenge` (#amount_must_be_whole_tenge) | 422 | Сумма счёта на номер телефона должна быть целой: тиыны Kaspi по такому счёту не принимает. Проверяется и голая amount, и итог корзины после скидок. Округлите сумму или выставьте счёт через POST /invoices/qr — там суммы с тиынами принимаются. В POST /invoices/bulk приходит по позиции: она попадает в invoices[] как failed, остальные создаются |
| `invoices_disabled` (#invoices_disabled) | 503 | Приём новых счетов временно приостановлен — идут технические работы. Счёт не создан, повторите позже. |

## Поле «error» только для QR-счёта (POST /invoices/qr)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `qr_rate_limit` (#qr_rate_limit) | 429 | Слишком много QR-запросов для организации (лимит 60/мин) — подождите минуту. Заголовок Retry-After на этом 429 не возвращается (в отличие от общего лимита Public API 200/мин) |
| `qr_render_failed` (#qr_render_failed) | 500 | Не удалось сформировать изображение QR-кода — повторите запрос позже |
| `kaspi_error` (#kaspi_error) | 502 | Kaspi API вернул ошибку при создании QR-токена — повторите позже |

## Поле «error» при отмене и возврате

| Код | HTTP | Что это и что делать |
|---|---|---|
| `Invoice cannot be cancelled` (#invoice-cannot-be-cancelled) | 400 | Отменить можно только счёт в статусе pending или processing |
| `Invoice is not refundable` (#invoice-is-not-refundable) | 400 | Возврат возможен только по оплаченному счёту, ещё не возвращённому полностью |
| `Refund amount exceeds available amount` (#refund-amount-exceeds-available-amount) | 400 | Сумма возврата больше доступной — смотрите available_for_refund в GET /invoices/{id} |
| `qr_cancel_unsupported` (#qr_cancel_unsupported) | 409 | QR-счёт (is_qr_token: true) отменить нельзя — отмена для него не поддерживается. Статус счёта не меняется, в Kaspi ничего не уходит. В теле ответа есть expires_at — момент, после которого QR перестанет быть оплачиваемым; дождитесь статуса expired или выставьте новый счёт |

## Поле «error» при работе с подписками

| Код | HTTP | Что это и что делать |
|---|---|---|
| `sandbox_subscription_limit` (#sandbox_subscription_limit) | 400 | Достигнут лимит тестовых подписок (10 на организацию) — очистите песочницу |
| `Organization not verified` (#organization-not-verified) | 403 | Подписки в рабочем режиме доступны только верифицированной организации |

## Асинхронные ошибки Kaspi: status=error / поле error_message (HTTP-кода нет)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `status=error` (#status-error) | — | Счёт создан (201, статус processing), но Kaspi не смог его обработать — статус сменился на error. Причина текстом в поле error_message (GET /invoices/{id}). У Kaspi нет фиксированных кодов — текст приходит как есть |
| `error_message: номер не в Kaspi` (#error-message-nomer-ne-v-kaspi) | — | «Этот номер телефона не зарегистрирован в Kaspi. Укажите номер с установленным приложением Kaspi.» — у клиента нет приложения Kaspi; попросите другой номер |
| `error_message: сбой Kaspi` (#error-message-sboy-kaspi) | — | «Ошибка обработки платежа. Обратитесь в поддержку» или «Не удалось обработать счёт после нескольких попыток» — временный сбой Kaspi; повторите создание счёта позже |

## Поле error_code — стабильный машинный код (новое, рекомендуется)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `error_code (новое поле)` (#error-code-novoe-pole) | — | Стабильный snake_case-код ошибки из фиксированного каталога. Присутствует в JSON-ответах об ошибках и в webhook-объектах invoice (для status=error) и refund (для status=failed). Поля message/error сохранены без изменений. Определяйте тип ошибки по error_code, текст — для показа пользователю. У каждого кода ниже указана «Доставка» — приходит ли он асинхронно (в webhook) или синхронно (HTTP-ответ с кодом) |
| `network_unavailable` (#network_unavailable) | — | Сервис временно недоступен (сбой сети/Kaspi). Можно повторить позже. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
| `session_transient` (#session_transient) | — | Временные проблемы авторизации Kaspi. Можно повторить попытку. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
| `client_not_found` (#client_not_found) | — | Номер телефона не зарегистрирован в Kaspi. Не повторяемая — попросите другой номер. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
| `kaspi_throttled` (#kaspi_throttled) | — | Kaspi ограничил частоту запросов. Повторите через 2–3 минуты. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
| `refund_window_expired` (#refund_window_expired) | — | Срок возврата истёк или возврат уже сделан (часто для refund status=failed). Доставка: async — приходит в invoice.refunded (refund.error_code) |
| `refund_rejected_by_kaspi` (#refund_rejected_by_kaspi) | — | Kaspi отклонил возврат по этой операции. Отказ может быть временным — попробуйте позже ещё раз. Если не получится, выполните возврат вручную в приложении Kaspi Pay. Сервис сам этот возврат не повторяет: строка сразу финальная, повтор — ваш новый запрос на возврат. Доставка: async — приходит в invoice.refunded (refund.error_code) |
| `refund_requires_buyer_confirmation` (#refund_requires_buyer_confirmation) | — | Kaspi требует подтверждение покупателя. Создайте QR-возврат через POST /api/v1/qr-refunds и попросите покупателя отсканировать QR-код. Доставка: async — приходит в invoice.refunded (refund.error_code) |
| `invoice_already_paid` (#invoice_already_paid) | — | Счёт уже оплачен. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
| `invoice_already_cancelled` (#invoice_already_cancelled) | — | Счёт уже отменён. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
| `invoice_not_found_in_kaspi` (#invoice_not_found_in_kaspi) | — | Счёт не найден в Kaspi. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
| `organization_not_configured` (#organization_not_configured) | — | Организация не настроена (нет рабочей привязки Kaspi). Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
| `unknown_error` (#unknown_error) | — | Непредвиденная ошибка обработки — обратитесь в поддержку. Доставка: async — приходит в invoice.status_changed (invoice.error_code) |
| `qr_render_failed` (#qr_render_failed-2) | 500 | Не удалось сформировать изображение QR-кода — повторите запрос. Доставка: sync HTTP 500 + async (webhook invoice.status_changed, status=error) |
| `kaspi_session_invalid` (#kaspi_session_invalid-2) | 503 | Сессия кассира Kaspi истекла или сброшена — переподключите кассира. Доставка: sync HTTP 503 + async (webhook invoice.status_changed, status=error) |
| `kaspi_session_unavailable` (#kaspi_session_unavailable) | 503 | Не удалось проверить сессию Kaspi — попробуйте позже. Доставка: sync HTTP 503; на GET /invoices/{id}/receipt этот код приходит с HTTP 409 |
| `manager_throttled` (#manager_throttled) | 429 | Слишком много операций — попробуйте позже. Доставка: sync HTTP 429 |
| `whatsapp_otp_throttled` (#whatsapp_otp_throttled) | 429 | Слишком частые запросы кода WhatsApp — попробуйте позже. Доставка: sync HTTP 429 |
| `whatsapp_gateway_error` (#whatsapp_gateway_error) | 500 | Не удалось отправить код WhatsApp — попробуйте ещё раз. Доставка: sync HTTP 500 |
| `subscription_payment_failed` (#subscription_payment_failed) | 502 | Не удалось создать счёт для оплаты подписки — попробуйте позже. Доставка: sync HTTP 502 |
| `kaspi_error` (#kaspi_error-2) | 502 | Kaspi API вернул ошибку — повторите позже. Текст message содержит конкретную причину от Kaspi. Доставка: sync HTTP 502 + async (для QR-счетов: webhook invoice.status_changed, status=error) |
| `trial_daily_limit` (#trial_daily_limit) | 429 | Антифрод/триал: на пробном тарифе превышен дневной лимит создания счетов (50 счетов/сутки). Дождитесь следующего дня или оформите подписку. Доставка: sync HTTP 429 + заголовок Retry-After |
| `tariff_limit_reached` (#tariff_limit_reached) | 429 | Исчерпан лимит счетов оплаченного тарифа (Старт 30, Бизнес 100, Про 300, Про Макс 600 в сутки). Считаются только счета, созданные через API; счета из кабинета и песочницы в лимит не входят. Разовое превышение не блокирует: отказ приходит при систематическом превышении лимита либо при исчерпанном бюджете у организаций на помесячном подсчёте. meta.mode различает окна (daily — расчётные сутки, monthly — блок 30 дней), meta.limit — потолок, meta.used — израсходовано, meta.reset_at — момент обнуления счётчика; повторять запрос раньше бессмысленно. Ограничение снимается переходом на тариф выше сразу после оплаты. Автосписания по подпискам, созданным через API, при действующем ограничении пропускают цикл, дата следующего списания не сдвигается. В POST /invoices/bulk отказ приходит поэлементно и несёт только error_code и message. Доставка: sync HTTP 429 + заголовок Retry-After |
| `outstanding_recipient_limit` (#outstanding_recipient_limit) | 429 | Антифрод: слишком много неоплаченных (outstanding) счетов на одного получателя. Дождитесь оплаты или истечения ранее выставленных счетов. Доставка: sync HTTP 429 + заголовок Retry-After |
| `outstanding_org_limit` (#outstanding_org_limit) | 429 | Антифрод: слишком много неоплаченных (outstanding) счетов по организации в целом. Дождитесь оплаты или истечения ранее выставленных счетов. Доставка: sync HTTP 429 + заголовок Retry-After |
| `recipient_fanout_exceeded` (#recipient_fanout_exceeded) | 429 | Антифрод: превышен темп рассылки счетов по разным получателям (fan-out). Снизьте частоту создания счетов на разные номера. Доставка: sync HTTP 429 + заголовок Retry-After |
| `content_rejected` (#content_rejected) | 422 | Антифрод: содержимое счёта (например текст описания) отклонено проверкой. Исправьте текст и повторите. Доставка: sync HTTP 422 |
| `description_too_long` (#description_too_long) | 422 | Описание счёта длиннее, чем Kaspi показывает покупателю: видны только первые 60 символов, остальное Kaspi отбрасывает. Укоротите описание — вынесите в начало то, по чему плательщик узнает платёж. Повтор с тем же телом бесполезен. Доставка: sync HTTP 422 |
| `field_too_long` (#field_too_long) | 422 | Значение поля слишком длинное. Имя поля лежит ключом в errors — укоротите именно его; повтор с тем же телом бесполезен. Страховочный код: обычно слишком длинное значение отсекается обычной ошибкой валидации, форма которой не менялась. В POST /invoices/bulk приходит не на весь запрос, а строкой в invoices[] у конкретной позиции: ответ остаётся 201, соседние счета созданы, повторить нужно только эту позицию. Доставка: sync HTTP 422 |
| `sandbox_simulated_error` (#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` (#cart_items_mismatch) | — | Зарезервирован — сейчас не используется бэкендом (такие случаи приходят как kaspi_error). Доставка: — |
| `image_upload_failed` (#image_upload_failed) | — | Зарезервирован — сейчас не используется бэкендом. Доставка: — |
| `catalog_item_not_found` (#catalog_item_not_found) | — | Зарезервирован — сейчас не используется бэкендом. Доставка: — |

## Каталог: чтение списка и ошибок (GET /catalog, GET /catalog/errors)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `catalog_batch_filter_removed` (#catalog_batch_filter_removed) | 422 | Фильтр по партии (batch_id) больше не поддерживается: агрегат партий удалён. Отбивается по самому наличию параметра, поэтому пустой batch_id тоже вернёт 422 — это сделано намеренно, чтобы старый интегратор увидел отказ, а не молча получил не тот набор. Подтверждайте свой набор точечным запросом GET /catalog?external_refs[]=..., остаток работы смотрите в GET /catalog/queue, отказы — в GET /catalog/errors с окном from и to по моменту отказа, push — событие catalog.item_processed. Доставка: sync HTTP 422 |

## Каталог: резолв штрихкода (POST /catalog/scan)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `kaspi_session_expired` (#kaspi_session_expired) | 400 | Сессия Kaspi мерчанта истекла — нужна переавторизация кассира Kaspi. Доставка: sync HTTP 400 |
| `kaspi_throttled` (#kaspi_throttled-2) | 429 | Kaspi троттлит сессию при сканировании. Повторить после паузы (тело retry_after_seconds, заголовок Retry-After). Circuit-breaker: ~90 с сразу отдаёт 429 без обращения к Kaspi. Доставка: sync HTTP 429. Примечание: отличается от async error_code kaspi_throttled по счетам |
| `kaspi_scan_unavailable` (#kaspi_scan_unavailable) | 503 | Нацкаталог Kaspi временно недоступен — повторить позже. Доставка: sync HTTP 503 |

## Каталог: приём позиций (POST /catalog)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `catalog_item_invalid` (#catalog_item_invalid) | — | Позиция не прошла валидацию: имя, цена, единица измерения или другое поле. Конкретика — в error_message и карте errors по позиции. Доставка: per-item в rejected[] ответа POST /catalog |
| `catalog_item_duplicate` (#catalog_item_duplicate) | — | Kaspi отклонил товар как похожий на уже существующий в вашем каталоге. Проверьте, нет ли позиции с тем же названием и штрихкодом, — если товар действительно новый, измените название так, чтобы оно отличалось |
| `barcode_too_long` (#barcode_too_long) | — | Штрихкод длиннее допустимого — не более 32 символов. Обрежьте значение или передайте позицию без штрихкода |

## Каталог: массовое удаление (POST /catalog/bulk-delete)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `catalog_delete_scope_required` (#catalog_delete_scope_required) | 422 | Не задан ни ids[], ни external_refs[], либо заданы оба списка сразу. Передайте ровно один список — сервер не додумывает, что именно вы хотите удалить |
| `catalog_match_overflow` (#catalog_match_overflow) | 422 | В списке слишком много значений — за один запрос принимается не более 200 ids или external_refs. Разбейте выборку на части |
| `catalog_bulk_delete_mismatch` (#catalog_bulk_delete_mismatch) | 409 | Переданный expected_count разошёлся с фактом: каталог изменился между разведкой и командой. В теле придёт actual_count — повторите dry_run и убедитесь, что удаляете то, что хотели. Поле expected_count необязательное, но при расхождении не удаляется ничего |
| `catalog_multi_tradepoint` (#catalog_multi_tradepoint) | 409 | У организации несколько торговых точек — массовое удаление для неё закрыто. Обратитесь в поддержку. У одиночного DELETE /catalog/{id} этот же код синхронно больше не приходит: запрос принимается с 202, а код появляется на самой позиции в error_code |
| `catalog_busy` (#catalog_busy) | 409 | Каталог занят другой операцией — повторите запрос через несколько секунд |
| `idempotency_key_conflict` (#idempotency_key_conflict) | 409 | Переданный Idempotency-Key уже занят другим телом либо другой каталожной операцией — пространство ключей общее. Возьмите новый ключ. Точный повтор ТОГО ЖЕ тела с тем же ключом конфликтом не считается: приходит 200 с idempotent_replay true, и ничего не удаляется повторно |
| `request_rate_limited` (#request_rate_limited) | 429 | Превышен лимит эндпоинта — 10 запросов в минуту. Разведка (dry_run) расходует тот же лимит. Пауза — в поле retry_after_seconds и в заголовке Retry-After |

## Тариф: индивидуальные условия

| Код | HTTP | Что это и что делать |
|---|---|---|
| `custom_tariff_locked` (#custom_tariff_locked) | 409 | У мерчанта индивидуальные условия тарифа: смена тарифа не самообслуживаемая и оформляется поддержкой. Продление ТОГО ЖЕ тарифа не блокируется — это оплата, а не смена условий. Определяйте состояние заранее: is_custom в GET /api/v1/tariff и can_change_tier в каталогах планов; повтор запроса не поможет |

## Каталог: паритет has_catalog ↔ cart_items

| Код | HTTP | Что это и что делать |
|---|---|---|
| `catalog_requires_cart_items` (#catalog_requires_cart_items) | 422 | У организации включён каталог товаров: счёт должен нести состав покупки. Передайте cart_items[] — идентификаторы позиций берутся из GET /catalog, цена строки при необходимости переопределяется полем price. Приходит на POST /invoices/qr и POST /static-qr. Создание подписки (POST /subscriptions) корзину тоже требует, но отвечает обычной ошибкой валидации по полю cart_items, без этого кода. Доставка: sync HTTP 422 (без ключа errors) |
| `catalog_not_supported` (#catalog_not_supported) | 422 | У организации каталог товаров выключен, а в запросе передана корзина. Уберите cart_items[] и передайте amount. Если каталог вам нужен — он включается вместе с Kaspi Кассой (ОФД), напишите нам. Доставка: sync HTTP 422 (без ключа errors), а в POST /invoices/bulk — per-item в разборе позиций |

## Подключение кассира (POST /connections/{connection}/auth/*)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `duplicate_cashier_confirm` (#duplicate_cashier_confirm) | 409 | Этот номер кассира уже подключён к другой организации того же владельца. Это не блокировка: повторите тот же запрос send-phone с confirm_duplicate: true. В теле — can_override и existing_organization с полями id, name, connection_status и invoices_count; connection_status относится к подключению, а не к организации |
| `entrance_auth_disabled` (#entrance_auth_disabled) | 503 | Подключение кассира временно недоступно — идут технические работы. Повторите позже, данные подключения не пострадали |

## Подключение кассира: сверка организации Kaspi

| Код | HTTP | Что это и что делать |
|---|---|---|
| `organization_identity_conflict` (#organization_identity_conflict) | 409 | Подключаемый кассир принадлежит другой организации Kaspi. Организация закрепляется за первой привязкой и подключением нового кассира не переносится. Подключайте кассира той организации, за которой эта уже закреплена, либо заводите отдельную организацию. В теле приходят только error и message: идентификаторов и названия другой организации в ответе нет. Если владелец бизнеса действительно сменился, напишите в поддержку 77003076512. Доставка: sync HTTP 409 |
| `organization_identity_unavailable` (#organization_identity_unavailable) | 502 | Kaspi не вернул достоверные данные организации, и сверить её в этой попытке не удалось. Попытка входа закрыта: начните заново с POST /connections/{connection}/auth/init, повторная отправка кода на закрытом процессе вернёт no_process. Уже подтверждённая ранее привязка не сбрасывается и не блокируется. В теле приходят только error и message, отдельного поля error_code нет — разбирайте error. Доставка: sync HTTP 502 |
| `connection_identity_unverified` (#connection_identity_unverified) | 422 | Основным нельзя назначить подключение, которое ещё не подтвердило организацию или заблокировано. Проведите вход кассира до конца и повторите. В теле приходят только error и message, отдельного поля error_code нет — разбирайте error. Доставка: sync HTTP 422 |

## KYC: верификация бизнеса и webhook-домен (новое)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `kyc_daily_limit_reached` (#kyc_daily_limit_reached) | 429 | Молодая организация: пока анкета о бизнесе не одобрена, доступен 1 реальный счёт в сутки (окно Asia/Almaty; счета в песочнице не считаются). Чтобы снять лимит — заполните короткую анкету «Расскажите о бизнесе» в кабинете (/business-profile), одобрение обычно за 1 рабочий день. Не повторяйте запрос до сброса. Доставка: sync HTTP 429 (meta.reset_at — когда лимит сбросится, meta.kyc_status — текущий статус) |
| `kyc_rejected` (#kyc_rejected) | 403 | Приём платежей недоступен по итогам проверки бизнеса (статус организации blocked). Не повторяемая — напишите в поддержку, если считаете это ошибкой. Доставка: sync HTTP 403 при создании счёта (POST /invoices, POST /invoices/qr) |
| `webhook_url_requires_domain` (#webhook_url_requires_domain) | 422 | Адрес webhook должен быть на вашем домене — IP-адреса не принимаются. Действует для ещё не одобренных организаций в рабочем режиме; в песочнице правило мягче. Укажите публичный HTTPS-адрес на домене. Доставка: sync HTTP 422 при сохранении webhook-URL |
| `webhook_url_tunnel_forbidden` (#webhook_url_tunnel_forbidden) | 422 | Туннели (ngrok и подобные) нельзя использовать для рабочих webhook — они временны и отключатся, уведомления перестанут приходить. Укажите адрес на вашем домене. Действует для ещё не одобренных организаций в рабочем режиме; в песочнице туннель для локального теста допустим. Доставка: sync HTTP 422 при сохранении webhook-URL |

## Фискальные чеки (Kaspi OFD)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `fiscal_receipts_disabled` (#fiscal_receipts_disabled) | 403 | Выбивание чеков отключено для боевых организаций (фича включается постепенно). В песочнице чеки работают всегда — обкатайте интеграцию там. Не повторяемая. Доставка: sync HTTP 403 |
| `not_sandbox` (#not_sandbox) | 403 | Поле simulate прислано боевой организацией — форсировать исход чека можно только в песочнице. Чек не создан. Уберите simulate из тела запроса. Доставка: sync HTTP 403 (POST /receipts) |
| `kaspi_session_not_configured` (#kaspi_session_not_configured-2) | 409 | К организации не привязан кассир Kaspi Pay — выбить чек не через кого. Подключите кассира в кабинете (Настройки → Подключение кассира). Доставка: sync HTTP 409 |
| `duplicate_client_operation_id` (#duplicate_client_operation_id) | 409 | Чек с таким client_operation_id уже выбивался — второй раз он не пробьётся (идемпотентность). В теле ответа приходит receipt_id существующего чека: опросите его через GET /receipts/{id}. Повтор после failed разрешён, но с НОВЫМ ключом. Доставка: sync HTTP 409 |
| `connection_ambiguous` (#connection_ambiguous-2) | 422 | К организации привязано несколько кассиров — непонятно, через какого выбивать чек. Передайте kaspi_connection_id явно. Доставка: sync HTTP 422 |
| `receipt_preview_unavailable` (#receipt_preview_unavailable) | 503 | Предпросмотр чека временно недоступен (POST /receipts/preview). Повторяемая — попробуйте позже; на выбивание самого чека не влияет. Доставка: sync HTTP 503 |
| `receipt_not_found` (#receipt_not_found) | 404 | Чек не найден или принадлежит другой организации. Доставка: sync HTTP 404 (GET /receipts/{id}) |
| `shift_closed` (#shift_closed) | — | Смена на кассе закрыта — чек выбить нельзя. Откройте смену в приложении Kaspi Pos и повторите с новым client_operation_id. В песочнице воспроизводится через simulate. Доставка: async, status=failed (GET /receipts/{id}, вебхук receipt.failed) |
| `item_not_fiscal` (#item_not_fiscal) | — | В чеке есть позиция, не зарегистрированная фискально: у товара должны быть и штрихкод (barcode), и НТИН Нацкаталога (ntin). Дозаполните НТИН в каталоге (PATCH /catalog/{id}) — позиция станет фискальной. Позиции без НТИН удобно найти через GET /catalog?without_ntin=true. Правило одинаково в бою и в песочнице. Доставка: async, status=failed |
| `rfo_missing` (#rfo_missing) | — | У кассира не настроен фискальный регистратор (РФО) — Kaspi не может зарегистрировать чек. Проверьте настройки кассы в Kaspi Pos. Доставка: async, status=failed |
| `receipt_kaspi_error` (#receipt_kaspi_error) | — | Kaspi отклонил выбивание чека; подробности — в поле error_message чека. Повтор возможен с НОВЫМ client_operation_id. В песочнице воспроизводится через simulate. Доставка: async, status=failed |
| `receipt_dispatch_error` (#receipt_dispatch_error) | — | Не удалось отправить чек в Kaspi (сеть или временный сбой). Повторяемая — попробуйте ещё раз с новым client_operation_id. Доставка: async, status=failed |
| `receipt_ofd_token_revoked` (#receipt_ofd_token_revoked) | — | Фискальная привязка кассы отозвана — мерчанту нужно перепривязать ОФД в приложении Kaspi. Приём оплат при этом работает: счета и QR продолжают создаваться, встают только чек и изменяющий каталог. Не путайте с kaspi_session_invalid — платёжная сессия жива, переподключение кассира не поможет. Повтор имеет смысл только ПОСЛЕ перепривязки ОФД, временем не лечится. Доставка: async, status=failed |

## Чек Kaspi по счёту (GET /invoices/{id}/receipt)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `receipt_not_available_for_status` (#receipt_not_available_for_status) | 409 | Чек есть только у оплаченного или частично возвращённого счёта. Проверьте status счёта перед запросом. Тот же код приходит, если у оплаченного счёта ещё нет числового идентификатора Kaspi — чек по такому счёту получить нельзя. Не повторяемая. Доставка: sync HTTP 409 |
| `kaspi_session_expired` (#kaspi_session_expired-2) | 409 | Кассир, через которого прошла оплата, требует переподключения — чек получить нельзя, пока кассир не подключён заново. Счёт и оплата не затронуты. Доставка: sync HTTP 409 |
| `kaspi_session_unavailable` (#kaspi_session_unavailable-2) | 409 | Кассир по счёту сейчас недоступен — повторите позже; если повторяется, проверьте подключение кассира в кабинете. Доставка: sync HTTP 409 |
| `receipt_rate_limited` (#receipt_rate_limited) | 429 | Запросов чеков слишком много — у ручки отдельный лимит. Повторите через минуту. Доставка: sync HTTP 429 |
| `receipt_unavailable` (#receipt_unavailable) | 503 | Чек получить не удалось. Повторяемая — попробуйте через минуту. Счёт и оплата не затронуты. Доставка: sync HTTP 503 |

## Возврат по QR (клиент подтверждает сканированием)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `qr_refund_not_identified` (#qr_refund_not_identified) | 409 | Покупатель ещё не отсканировал возвратный QR. Приходит на GET /qr-refunds/{id}/operations и на execute. Не ошибка интеграции — дождитесь статуса customer_identified (поллинг GET /qr-refunds/{id} или вебхук qr_refund.identified). Сессия жива. |
| `qr_refund_expired` (#qr_refund_expired) | 409 | Срок сессии истёк. У сессии ДВА срока: сам QR живёт минуты (expires_at), и отдельно ограничено время на выбор операции после подтверждения покупателем. Возврат не сделан — начните новую сессию. Не повторяемая. |
| `qr_refund_completed` (#qr_refund_completed) | 409 | Возврат по этой сессии уже выполнен. Повторный execute не пройдёт (идемпотентность). Не считайте это отказом: запросите GET /qr-refunds/{id} и возьмите refunded_amount и receipt_url оттуда. |
| `operation_not_returnable` (#operation_not_returnable) | 422 | Kaspi не разрешает возврат по выбранной операции (returnable: none) — срок возврата истёк либо деньги уже возвращены. Сессия остаётся живой: выберите другую покупку. |
| `refund_amount_exceeds_available` (#refund_amount_exceeds_available) | 422 | Сумма больше доступной к возврату. Актуальное значение — в available_for_refund из GET /qr-refunds/{id}/operations/{ref}. Сессия жива, можно повторить с корректной суммой. |
| `partial_refund_requires_return_items` (#partial_refund_requires_return_items) | 422 | Эту покупку Kaspi возвращает только по позициям: пришлите items вместо amount. Напоминание: amount и items взаимоисключимы. |
| `not_found` (#not_found) | 404 | Сессия не найдена или принадлежит другой организации — код ответа одинаков в обоих случаях (не оракул чужих сессий). Начните новую сессию. |
| `not_sandbox` (#not_sandbox-2) | 403 | Поле simulate или POST /qr-refunds/{id}/simulate прислан боевой организацией — форсировать шаги покупателя можно только в песочнице. |

## Касса: смены, наличные, сверка (/cashbox/*)

| Код | HTTP | Что это и что делать |
|---|---|---|
| `cashbox_disabled` (#cashbox_disabled) | 403 | Кассовые операции для организации сейчас недоступны. В песочнице этот отказ не приходит. |
| `cashbox_kkm_unknown` (#cashbox_kkm_unknown) | 409 | Номер кассы (ККМ) для организации неизвестен. Он есть только у организаций с подключённой кассой Kaspi (ОФД) — той же, что включает каталог товаров. Если продажи идут через Kaspi Pos без ОФД, ждать нечего: кассовых смен у такой организации не существует. Если Kaspi Касса подключена, проверьте, что кассир подключён и его сессия активна; при нескольких кассах укажите kaspi_connection_id нужной точки. Если код продолжает приходить — напишите в поддержку. |
| `rfo_missing` (#rfo_missing-2) | 409 | Код торговой точки Kaspi не определён: этим кодом отвечают GET /cashbox/summary и оба тумблера настроек. Чаще всего это значит, что к аккаунту Kaspi Pay не подключена касса Kaspi (ОФД) — тогда кассовых смен у организации не существует. Если Kaspi Касса подключена, при нескольких кассах передавайте kaspi_connection_id нужной точки, а состояние организации пересверяется переподключением кассира или кнопкой «Обновить информацию об организации» в настройках кабинета. ⚠️ Это действие может включить каталог товаров: после него POST /invoices/qr и POST /static-qr без cart_items отвечают 422 catalog_requires_cart_items, а напечатанные QR-листы без состава перестают работать. Тот же код приходит и в фискальном контуре, по той же причине: чек не выбивается, пока код торговой точки не определён. |
| `cashbox_no_open_shift (см. operation.error_code)` (#cashbox-no-open-shift-sm-operation-error-code) | — | Открытой смены на кассе нет — закрывать нечего. |
| `cashbox_shift_already_closed` (#cashbox_shift_already_closed) | — | Смена уже закрыта. Для операции закрытия это успешный исход: целевое состояние достигнуто. |
| `cashbox_shift_not_found` (#cashbox_shift_not_found) | 404 | Смена с таким id недоступна. Возьмите id из GET /cashbox/shifts. |
| `cashbox_operation_not_found` (#cashbox_operation_not_found) | 404 | Операция не найдена или принадлежит другой организации — код ответа одинаков в обоих случаях. |
| `cashbox_duplicate_operation` (#cashbox_duplicate_operation) | 409 | client_operation_id уже использован. В теле ответа приходит operation_id принятой операции — по нему продолжайте поллинг; для нового закрытия возьмите новый ключ. Ключ не освобождается даже после failed. |
| `cashbox_busy (см. operation.error_code)` (#cashbox-busy-sm-operation-error-code) | — | Касса занята другой операцией. Повторите позже новым client_operation_id. |
| `cashbox_operation_failed (см. operation.error_code)` (#cashbox-operation-failed-sm-operation-error-code) | — | Kaspi не выполнил операцию. При resolution.safe_to_retry=false автоматический повтор небезопасен — решение оставьте человеку. |
| `cashbox_unavailable` (#cashbox_unavailable) | 503 | Касса Kaspi временно недоступна, данные получить не удалось. Повторите позже. |
| `cashbox_report_unavailable` (#cashbox_report_unavailable) | 503 | Отчёт по смене получить не удалось. Повторите позже. |
| `cashbox_toggle_in_progress` (#cashbox_toggle_in_progress) | 503 | Переключение тумблера уже выполняется. Повторите позже. |
| `cashbox_toggle_unavailable` (#cashbox_toggle_unavailable) | 503 | Текущее значение на кассе проверить не удалось — переключение не выполнено. Повторите позже. |

---

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