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

# Хаталар

> Бер конверт, тотрыклы кодлар һәм һәр җавапта сорау идентификаторы.

## Конверт

Һәр уңышсызлык, статусына карамастан, бер JSON объекты:

```json theme={null}
{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance",
    "request_id": "7f20a5f0-5dde-48cf-94aa-38acbbd218e0"
  }
}
```

* `code` тотрыклы һәм машина укырлык. `message` буенча түгел, аның буенча тармакланыгыз.
* `message` — кеше укырлык аңлатма, ул үзгәрергә мөмкин.
* `request_id` — сорауның UUID-ы. Ул **һәр** җавапта, уңышлымы, уңышсызмы, `X-Request-ID` башламы буларак та кайтарыла. Проблема турында хәбәр иткәндә аны күрсәтегез.

Агымлы эндпоинтта агым башланганнан соң булган уңышсызлык шул ук өч кырлы `error` вакыйгасы буларак килә; [Агымлы җавап](/tt/guides/streaming) битен карагыз.

## Кодлар

| HTTP | Код                          | Мәгънәсе                                                                                                  |
| ---- | ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| 401  | `invalid_api_key`            | Юк, дөрес формада булмаган, билгесез, юылган яки сере ялгыш ачкыч                                         |
| 403  | `agent_mismatch`             | Ачкыч башка агентныкы                                                                                     |
| 403  | `permission_denied`          | `read-only` ачкыч чат эндпоинтын чакырган                                                                 |
| 403  | `agent_disabled`             | Агент сүндерелгән. Чат эндпоинтларында гына                                                               |
| 404  | `agent_not_found`            | Агент инде юк. Чат эндпоинтларында гына                                                                   |
| 404  | `conversation_not_found`     | Билгесез диалог яки бу ачкычныкы булмаган диалог                                                          |
| 402  | `insufficient_balance`       | Хуҗаның балансы җавапны каплый алмый; бернәрсә дә алынмады                                                |
| 409  | `idempotency_conflict`       | Шул ук `Idempotency-Key` башка тән белән кулланылган                                                      |
| 409  | `idempotency_in_progress`    | Баштагы сорау әле үтәлә; `Retry-After` секунд үткәч кабатлагыз (һәрвакыт `2`)                             |
| 409  | `conversation_busy`          | Шул ук тышкы кулланучы өчен башка хәбәргә җавап бирелә; `Retry-After` үткәч кабатлагыз (һәрвакыт `2`)     |
| 422  | `validation_error`           | Ялгыш тән, башлам, дата, лимит яки курсор                                                                 |
| 429  | `rate_limit_exceeded`        | Ачкычның тәрәзәсе тулган; [Сораулар лимитлары](/tt/guides/rate-limits) битен карагыз                      |
| 503  | `api_rate_limit_unavailable` | Лимитлаучы эшләми; сорау исәпсез үтәлү урынына кире кагыла. `Retry-After` үткәч кабатлагыз (һәрвакыт `5`) |
| 503  | `service_unavailable`        | API бәйле булган бэкенд эшләми; `Retry-After` үткәч кабатлагыз (һәрвакыт `2`)                             |
| 500  | `internal_error`             | Көтелмәгән уңышсызлык; `request_id` күрсәтегез                                                            |

`agent_not_found` һәм `agent_disabled` `POST …/chat` һәм `POST …/chat/stream` тарафыннан гына тикшерелә. Ике `GET` эндпоинты агентның халәтенә карамый: сүндерелгән агентның ачкычы барыбер аның диалоглары исемлеген ала һәм хәбәрләрен укый ала.

## Нәрсәне кабатларга

<AccordionGroup>
  <Accordion title="Retry-After үткәч, шул ук Idempotency-Key белән кабатлагыз">
    `idempotency_in_progress`, `conversation_busy`, `rate_limit_exceeded`, `api_rate_limit_unavailable`, `service_unavailable`. Ачкычны кабат куллану бер үк хәбәр өчен беркайчан да ике тапкыр түләмәвегезне гарантияли.
  </Accordion>

  <Accordion title="Башта сорауны төзәтегез">
    `validation_error` (`message` укыгыз; ул ялгыш кырны атый), `idempotency_conflict` (яңа тән өчен яңа ачкыч кулланыгыз), `permission_denied` (`full` ачкыч кулланыгыз), `agent_mismatch` (ачкыч караган агентны кулланыгыз).
  </Accordion>

  <Accordion title="Автоматик рәвештә кабатламагыз">
    `invalid_api_key` (ачкыч юылган яки сере ялгыш), `agent_disabled`, `agent_not_found`, `insufficient_balance` (башта балансны тутырыгыз). Болар өчен кабатлау циклы сораулар лимитын гына сарыф итә.
  </Accordion>

  <Accordion title="Сорау идентификаторы белән хәбәр итегез">
    `internal_error`. Шул ук `Idempotency-Key` белән бер тапкыр кабатлагыз: уңышсыз язма азат ителә, шуңа күрә кабатлау сакланган нәтиҗәне кайтармый, ә сорауны яңадан үтәтә. Бу көтелгән хәл, әмма бушлай булуы гарантияләнми. Модель инде җавап биргәннән соң уңышсызлык булган булса, кабатлау яңа җавап һәм яңа түләү ясый. Хәл кабатланса, безгә `request_id` җибәрегез.
  </Accordion>
</AccordionGroup>

## 401 турында искәрмә

API юылган ачкычны беркайчан булмаган ачкычтан аермый: икесе дә `invalid_api_key`. Элек эшләгән ачкыч 401 кайтара башласа, кушымтадагы API аша керү карточкасын тикшерегез; ул, мөгаен, яңартылган яки юылган.