> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tungo.kz/llms.txt
> Use this file to discover all available pages before exploring further.

# Қателер мен шектеулер

> Қате туралы жауап қалай құрылған, қай өрістер бойынша тармақталу керек, бас тартулардың негізгі кодтары және сұраулар жиілігінің шектеулері.

API-дің кез келген қатесі бір түрде келеді: HTTP күйі 4xx немесе 5xx және қатенің түрі, коды мен адамға арналған мәтіні бар JSON. `error.type` және `error.code` өрістері бойынша тармақталыңыз. `error.message` мәтінін сол күйінде көрсетіңіз немесе журналға жазыңыз, бірақ оны бағдарламамен талдамаңыз: тұжырымдар өзгеріп тұрады.

## Қате қалай көрінеді

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "payment_required_error",
    "code": "platform_balance_exhausted",
    "message": "…"
  },
  "request_id": "req_…"
}
```

`error.type` өрісі әрқашан бар, және әр түрдің өз HTTP күйі болады. `error.code` өрісі себепті нақтылайды. Ол барлық қатеде бола бермейді: ол жоқ болса, түр мен мәтін жеткілікті. Бейтаныс кодты түрі бойынша өңдеңіз.

`request_id` өрісі — сұраудың нөмірі. Сол нөмір әр жауаптың, оның ішінде сәтті жауаптың да, `x-request-id` тақырыбында келеді. Оны өз журналыңызда сақтаңыз: сол бойынша сұрау «Сұраулар журналы» бөлімінен табылады.

Сұрау өрістерді тексеруден өтпесе, `validation_failed` кодымен 400 келеді. Сонда `error.fields` ішінде әр өрісте не дұрыс емес екені тізіледі: жол, код және мәтін.

## Негізгі бас тартулар

Басты айырмашылық — бас тарту өздігінен өте ме, жоқ па. Жиілікке байланысты бас тарту өтеді: күте тұрып, қайталаңыз. Ақшаға, құқықтарға немесе кілттің күйіне байланысты бас тарту кабинеттегі адам бірдеңені өзгертпейінше өтпейді. Мұндай сұрауды циклмен қайталаудан пайда жоқ.

| Күй | `error.code` | Не болды | Не істеу керек |
| - | - | - | - |
| 401 | `missing_credentials` | Сұрауда кілт жоқ | `x-api-key` тақырыбын беру |
| 401 | `invalid_api_key` | Кілт қате | Кілттің толық көшірілгенін тексеру |
| 401 | `key_disabled`, `key_expired`, `key_revoked` | Кілт өшірілген, мерзімі өткен немесе кері қайтарылған | Қосу, қайта шығару немесе жаңасын шығару |
| 401 | `key_creator_lost_access` | Кілт авторы енді ие де, әкімші де емес | Кілтті басқа адамға беру |
| 402 | `platform_balance_exhausted` | Платформа балансы бос | Балансты толтыру |
| 402 | `platform_cap_reached` | Ұйымның айлық шегіне жетті | Шекті көтеру немесе `resets_at` сәтін күту |
| 402 | `key_cap_reached` | Кілттің айлық шегіне жетті | Кілттің шегін көтеру немесе `resets_at` сәтін күту |
| 402 | `platform_disabled` | Платформа ұйымда өшірілген | Платформаны қосу |
| 403 | `missing_permission` | Кілтте керек құқық жоқ, қайсысы екені — `error.permission` ішінде | Құқық беру немесе басқа кілт шығару |
| 403 | `ip_not_allowed` | Сұрау кілт тізімінде жоқ мекенжайдан келді | Рұқсат етілген мекенжайдан шақыру немесе тізімді түзету |
| 403 | `api_keys_disabled_by_policy` | Ұйым API кілттеріне тыйым салған | Ұйым иесіне жүгіну |
| 404 | жоқ | Объект жоқ немесе ол бөгде | id мен кілттің компанияларын тексеру |
| 409 | `turn_in_progress` | Бұл чатта алдыңғы жауап әлі жүріп жатыр | Оның аяқталуын күту |
| 409 | `idempotency_in_progress` | Осы `Idempotency-Key` мәнімен жасалған бірінші сұрау әлі орындалып жатыр | Күте тұрып, қайталау |
| 422 | `idempotency_key_reused` | Бұл `Idempotency-Key` басқа сұрауда қолданылған | Жаңа мән алу |
| 429 | `rate_limited` | Сұраулар тым көп | `Retry-After` ішінде қанша секунд көрсетілсе, сонша күту |
| 429 | `concurrent_turns_limit` | Кілт бойынша ЖИ-бухгалтер жауаптарының шекті саны жүріп жатыр | Олардың біреуінің аяқталуын күту |
| 500, 503 | жоқ | Ақау немесе уақытша қолжетімсіздік | Кейінірек қайталау |

Бөгде ұйымдар, компаниялар және құжаттар 403 емес, 404 қайтарады. Осылай API олардың бар екенін ашпайды. Компания анық бар болса, ал сұрау 404 қайтарса, оның кілт компанияларына кіретінін тексеріңіз.

ЖИ-бухгалтерге жіберілген сұрауға кодсыз келген 409 күйі көбінесе компанияның 1С-ке қосылмағанын білдіреді. Себебі `error.message` ішінде жазылған. Қосылым күйін `GET /v1/companies/{co}/onec/status` көрсетеді.

401 және 402 бас тартулары туралы [Кілт жұмыс істемейді](https://docs.tungo.kz/kk/platform/key-not-working.md) бетінде толығырақ жазылған. Кодтардың толық тізімі API анықтамасында, қатенің сипаттамасында бар.

## Сұраулар жиілігі

Кілт бойынша сұраулар минут сайын есептеледі. Шек екеу: бір кілтке және ұйымның барлық кілтіне бірге. Қайсысы тарырақ болса, сол қолданылады. Кілт бойынша әр жауапта үш тақырып болады, солардан қанша қалғаны көрінеді:

* `x-ratelimit-limit` — ағымдағы терезеде қанша сұрау жіберуге болады.
* `x-ratelimit-remaining` — олардың қаншасы қалды.
* `x-ratelimit-reset` — жаңа терезе неше секундтан кейін басталады.

Шектен асқанда `rate_limited` кодымен және секундпен берілген `Retry-After` тақырыбымен 429 келеді. Көрсетілген уақытты күтіп, сұрауды қайталаңыз. Қате кілтпен тым көп сұрау келген мекенжай да осы бас тартуды алады.

Шектердің өзі бұл құжаттамада келтірілмейді, өйткені олар өзгеруі мүмкін. Қолданыстағы мәндер мен кілт бойынша қалдықты мына сұрау береді:

```sh theme={null}
curl "$TUNGO_API/v1/workspaces/$WS/platform/limits" -H "x-api-key: $TUNGO_KEY"
```

Кабинетте мұны «Шектер» бөлімі көрсетеді: кілтті таңдаңыз, сонда оның дәл қазір қанша қалғанын көресіз.

## ЖИ-бухгалтерге бір мезгілде жіберілетін сұраулар

Бір кілт бойынша бір мезгілде ЖИ-бухгалтердің шектеулі жауабы ғана жүре алады. Бұл — бөлек шектеу, оның жиілікке қатысы жоқ. Одан асқан сұрау `concurrent_turns_limit` кодымен және `Retry-After` тақырыбымен 429 алады. Ағымдағы шек пен бос емес орындар саны сол шектер сұрауының жауабында, `concurrent_turns` өрісінде жатыр.

Бірден көп сұрақ қою керек болса, оларды өз жағыңызда кезекке қойып, бір мезгілдегі сұраулар санын шектен төмен ұстаңыз. Бір чатта жауаптар қатаң түрде бір-бірден жүреді.

## Сұраулардың өлшемдері

ЖИ-бухгалтерге қойылатын сұрақ 4000 таңбаға дейінгі ұзындықта қабылданады. Сұраққа файлдар тіркеуге болады. Қанша файлға және қандай өлшемге рұқсат етілетінін, сондай-ақ сұрау денесінің ең үлкен өлшемін сол шектер сұрауы `files` өрісінде береді. Тым үлкен сұрау `payload_too_large` кодымен 413 алады.

## Браузерден шақыру

API браузердегі бет кодынан келетін сұрауларды, яғни CORS-ты қолдамайды. Кілт — құпия, ал браузерде оны кез келген келуші көреді. `/v1` мекенжайларына жіберілген алдын ала `OPTIONS` сұрауы `cors_not_supported` кодымен 403 қайтарады. API-ді өз серверіңізден шақырыңыз, ал бетке дайын нәтижені беріңіз.

## Әрі қарай

* [Кілт жұмыс істемейді](https://docs.tungo.kz/kk/platform/key-not-working.md): бас тартуларды бір-бірлеп, әрекеттерімен талдау.
* [Платформа балансы және шығын](https://docs.tungo.kz/kk/platform/balance.md): 402 келуіне себеп болатын толтыру мен шектер.
* [Алғашқы сұрауды жіберу](https://docs.tungo.kz/kk/platform/first-request.md): `Idempotency-Key` тақырыбы және қауіпсіз қайталаулар.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.