Қысқаша
Әр қате { "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 кілтті кассирге байлау.
Kaspi байланысы
| Код | HTTP | Не болды | Не істеу керек |
|---|---|---|---|
kaspi_session_expired | 409 | Кассир байланысы үзілген | Қайта байланыстырыңыз: Байланыс үзілді |
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 код экранын көрсетпеді | Нөмір жарамайды: Үш шарт |
Счёт жасау
| Код | 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 екеуі екі басқа нәрсе. Біріншісі — тәуліктік қорғаныс, әдетте кодтағы цикл. Екіншісі — сіздің тарифіңіздің айлық лимиті. Толығы: Тарифтер және лимиттер.
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 келмей жатыр.
Жазылым
| Код | 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 бетінен қараңыз немесе қолдауға жазыңыз.
Қай қатені клиентке көрсетуге болады? Ешқайсысын тікелей көрсетпеңіз. Клиентке «төлем өтпеді, қайталап көріңіз» деп жазып, техникалық мәтінді өз журналыңызға жазыңыз.