# Қателер каталогы — API не қайтарады және не істеу керек

> Qut Pay API-інің барлық негізгі қате кодтары топтап берілген: авторизация, Kaspi байланысы, счёт, қайтару, тариф лимиті, webhook, жазылым. Әрқайсысының себебі және шешімі.

## Қысқаша

Әр қате `{ "error": "код", "message": "түсіндірме" }` түрінде келеді. HTTP күйі қатенің түрін көрсетеді: **4xx** — сұрауда бірдеңе дұрыс емес, түзетіп қайталау керек; **429** — лимит, күте тұру керек; **5xx** — біздің немесе Kaspi жағындағы уақытша ақау, қайталауға болады.

Интеграцияңызды `message` мәтініне емес, әрқашан `error` кодына қарап жазыңыз: мәтін өзгеруі мүмкін, код өзгермейді.

## Авторизация және кілт

| Код | HTTP | Не болды | Не істеу керек |
|---|---|---|---|
| `unauthorized` | 401 | Кілт жіберілмеген немесе жарамсыз | `X-API-Key` тақырыбын тексеріңіз |
| `invalid_api_key` | 422 | Кілттің пішімі дұрыс емес | Кілт `qp_live_…` немесе `qp_test_…` болуы керек |
| `insufficient_scope` | 403 | Кілтте бұл әрекетке құқық жоқ | Кабинетте кілтке керекті scope қосыңыз |
| `forbidden` | 403 | Бұл ресурс сіздің ұйымыңызға тиесілі емес | Кілт пен счёт бір ұйымға тиесілі ме, тексеріңіз |
| `account_blocked` | 403 | Аккаунт бөгелген | Қолдауға жазыңыз |
| `organization_inactive` | 410 | Ұйым архивте немесе өшірілген | Қолдауға жазыңыз |
| `not_sandbox` | 403 | Бұл әрекет тек sandbox-та істейді | Мысалы төлемді симуляциялау live режимде жұмыс істемейді |

`forbidden` пен `invoice_not_found` кілт байланған кассирге де қатысты: байланған кілт басқа кассирдің счёттарын көрмейді. Толығы: [API кілтті кассирге байлау](/kb/api-key-connection).

## Kaspi байланысы

| Код | HTTP | Не болды | Не істеу керек |
|---|---|---|---|
| `kaspi_session_expired` | 409 | Кассир байланысы үзілген | Қайта байланыстырыңыз: [Байланыс үзілді](/kb/connection-lost) |
| `kaspi_session_not_configured` | 409 | Кассир әлі қосылмаған | Кабинет → Kaspi → Кассир қосу |
| `connection_not_active` | 400 | Байланыс бар, бірақ белсенді емес | Сол кассирді қайта байланыстырыңыз |
| `connection_not_found` | 404 | Көрсетілген `connection_id` табылмады | Идентификаторды тексеріңіз |
| `no_provider` | 409 | Ұйымда бірде-бір жұмыс істейтін кассир жоқ | Кассир қосыңыз немесе sandbox-қа ауысыңыз |
| `connection_has_keys` | 409 | Бұл кассирге API кілт байланған, жою мүмкін емес | Алдымен кілтті басқа кассирге ауыстырыңыз |
| `cashier_number_rejected` | 502 | Kaspi код экранын көрсетпеді | Нөмір жарамайды: [Үш шарт](/kb/cashier-number-requirements) |

## Счёт жасау

| Код | HTTP | Не болды | Не істеу керек |
|---|---|---|---|
| `invalid_amount` | 422 | Сома жоқ немесе сан емес | Оң сан жіберіңіз |
| `amount_too_small` | 422 | Сома ең төменгі шектен аз | Сомасын көбейтіңіз |
| `amount_too_large` | 422 | Сома ең жоғарғы шектен көп | Сомасын азайтыңыз немесе бөліп жіберіңіз |
| `amount_must_be_whole_tenge` | 422 | Тиын жіберілген | Бүтін теңге жіберіңіз, Kaspi тиынды қабылдамайды |
| `invalid_phone` | 422 | Телефон пішімі дұрыс емес | `7XXXXXXXXXX` түрінде, 11 сан |
| `invalid_kind` | 422 | Белгісіз счёт түрі | `qr` немесе `phone` |
| `invoice_create_failed` | 502 | Kaspi счётты қабылдамады | Қайталаңыз; қайталана берсе қолдауға жазыңыз |
| `invoice_not_found` | 404 | Счёт жоқ немесе сізге көрінбейді | Идентификаторды және кілттің кассирін тексеріңіз |

## Счёттың күйі, болдырмау, қайтару

| Код | HTTP | Не болды | Не істеу керек |
|---|---|---|---|
| `invoice_not_open` | 409 | Счёт ашық емес: төленген, өтіп кеткен немесе болдырылған | Күйін `GET /invoices/{id}` арқылы қараңыз |
| `invoice_changed` | 409 | Сіз жұмыс істеп жатқанда счёттың күйі өзгерген | Күйін қайта оқып, шешім қабылдаңыз |
| `invoice_not_refundable` | 409 | Бұл счётты қайтаруға болмайды | Төленген бе, мерзімі өтпеген бе, тексеріңіз |
| `invalid_refund_amount` | 422 | Қайтару сомасы дұрыс емес | Төленген сомадан аспауы керек |
| `refund_failed` | 502 | Kaspi қайтаруды орындамады | Kaspi шотында ақша жеткілікті ме, тексеріңіз |
| `refund_unknown` | 502 | Kaspi жауап бермеді, нәтижесі белгісіз | Қайталамаңыз, счёт күйін оқып тексеріңіз |
| `refund_pending_unknown` | 409 | Алдыңғы қайтарудың нәтижесі әлі белгісіз | Күте тұрыңыз, екінші рет жібермеңіз |
| `refund_state_conflict` | 409 | Қайтару күйі күткеннен басқа | Счёт күйін қайта оқыңыз |
| `cancel_failed` | 502 | Kaspi счётты болдырмады | Қайталаңыз немесе счёттың өзі өтуін күтіңіз |

Қайтару кезінде `refund_unknown` немесе `refund_pending_unknown` келсе, **қайталап жібермеңіз** — екі рет қайтарып жіберуіңіз мүмкін. Счёттың күйін оқып, нәтижесін содан біліңіз.

## Тариф және лимиттер

| Код | HTTP | Не болды | Не істеу керек |
|---|---|---|---|
| `tariff_limit_reached` | 429 | Айлық счёт лимиті бітті | Тарифті көтеріңіз немесе жаңа айды күтіңіз |
| `tariff_daily_burst` | 429 | Бір тәулікте тым көп счёт | Бұл бизнес лимиті емес, циклге түскен интеграциядан қорғаныс. Кодыңызды тексеріңіз |
| `tariff_inactive` | 403 | Тариф белсенді емес немесе сынақ бітті | Кабинет → Тариф |
| `rate_limited` | 429 | Сұрау жиілігі шектен асты | `Retry-After` тақырыбын қараңыз, күтіп қайталаңыз |
| `request_rate_limited` | 429 | Жалпы сұрау жиілігі шектен асты | Сұрауларды сирекетіңіз |
| `too_many_attempts` | 429 | Бір әрекетті тым жиі қайталадыңыз | Бір минут күтіңіз |

`tariff_daily_burst` пен `tariff_limit_reached` екеуі екі басқа нәрсе. Біріншісі — тәуліктік қорғаныс, әдетте кодтағы цикл. Екіншісі — сіздің тарифіңіздің айлық лимиті. Толығы: [Тарифтер және лимиттер](/kb/tariff-limits).

## Webhook

| Код | HTTP | Не болды | Не істеу керек |
|---|---|---|---|
| `invalid_url` | 422 | Адрес дұрыс емес | Толық адрес жазыңыз |
| `webhook_url_requires_https` | 422 | HTTP адрес қабылданбайды | HTTPS қолданыңыз |
| `webhook_url_requires_domain` | 422 | IP немесе домені жоқ адрес | Нақты домен жазыңыз |
| `webhook_url_tunnel_forbidden` | 422 | Уақытша туннель адресі | Тұрақты домен қолданыңыз |
| `invalid_events` | 422 | Оқиға тізімі дұрыс емес | Қолдау көрсетілетін оқиға атауларын қараңыз |
| `too_many_endpoints` | 422 | Webhook саны шектен асты | Қажетсізін жойыңыз |
| `endpoint_not_found` | 404 | Webhook табылмады | Идентификаторды тексеріңіз |
| `hook_paused` | 410 | Форма-хук тоқтатылған | Кабинеттен қайта қосыңыз |

Webhook жетпей жатса, себебі көбіне қате кодында емес: [Webhook келмей жатыр](/kb/webhook-not-arriving).

## Жазылым

| Код | HTTP | Не болды | Не істеу керек |
|---|---|---|---|
| `invalid_interval` | 422 | Аралық дұрыс емес | `day`, `week` немесе `month` |
| `invalid_every` | 422 | Қайталау саны дұрыс емес | Оң бүтін сан |
| `invalid_retry` | 422 | Қайталау сатысы дұрыс емес | Ең көп 5 мән, әрқайсысы оң сан |
| `invalid_misfire` | 422 | Өткізіп алу саясаты дұрыс емес | `run_once` немесе `skip` |
| `invalid_max_runs` | 422 | Ең көп орындалу саны дұрыс емес | Оң бүтін сан |
| `subscription_closed` | 409 | Жазылым аяқталған немесе тоқтатылған | Жаңасын жасаңыз |
| `subscription_not_found` | 404 | Жазылым табылмады | Идентификаторды тексеріңіз |

## Төлем сілтемелері

| Код | HTTP | Не болды | Не істеу керек |
|---|---|---|---|
| `slug_taken` | 409 | Мұндай мекенжай бос емес | Басқа атау таңдаңыз |
| `link_invalid` | 410 | Сілтеме жарамсыз | Жаңасын жасаңыз |
| `link_paused` | 410 | Сілтеме тоқтатылған | Кабинеттен қайта қосыңыз |
| `too_many_links` | 409 | Сілтеме саны шектен асты | Қажетсізін жойыңыз |

## Кабинетке кіру

| Код | HTTP | Не болды | Не істеу керек |
|---|---|---|---|
| `invalid_code` | 400 | Код дұрыс емес | Қайта енгізіңіз |
| `challenge_expired` | 410 | Кодтың мерзімі өтті | Жаңа код сұраңыз |
| `challenge_used` | 409 | Код бұрын пайдаланылған | Жаңа код сұраңыз |
| `no_channel` | 503 | Код жіберетін арна жоқ | Қолдауға жазыңыз |
| `channel_forbidden` | 403 | Бұл арна сізге ашық емес | Басқа арнаны таңдаңыз |

## Қайталауға бола ма

| Түрі | Қайталау |
|---|---|
| 4xx (422, 400, 403, 404, 409) | Жоқ. Сұрауды түзетпей қайталаудың мәні жоқ |
| 429 | Иә, бірақ `Retry-After` көрсеткен уақыттан кейін |
| 502, 503 | Иә, өсіп отыратын кідіріспен (мысалы 1, 2, 4, 8 секунд) |
| `refund_unknown`, `refund_pending_unknown` | **Жоқ.** Алдымен счёт күйін оқыңыз |

Счёт жасауда қайталаудан қорғану үшін `idempotencyKey` жіберіңіз: сол кілтпен екінші рет жіберсеңіз, жаңа счёт жасалмай, бұрынғысы қайтады.

## Жиі қойылатын сұрақтар

**Қате мәтіні қазақша келе ме?** Иә, `message` өрісі қазақша. Бірақ интеграцияны `error` кодына қарап жазыңыз.

**Бұл тізімде жоқ код келді.** Толық спецификацияны [api.qut.kz/docs](https://api.qut.kz/docs) бетінен қараңыз немесе қолдауға жазыңыз.

**Қай қатені клиентке көрсетуге болады?** Ешқайсысын тікелей көрсетпеңіз. Клиентке «төлем өтпеді, қайталап көріңіз» деп жазып, техникалық мәтінді өз журналыңызға жазыңыз.