> ## 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` бо ҳамон се майдон мерасад; ниг. [Ҷавоби ҷараёнӣ](/tj/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`        | Равзанаи калид тамом шудааст; ниг. [Маҳдудияти дархостҳо](/tj/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-ро дар барнома тафтиш кунед; эҳтимол он навсозӣ ё ҳазф шудааст.