# Қателер

Әр соңғы нүкте бірдей тәсілмен қате қайтарады: HTTP күйі және бір JSON конверті.

```json
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 5, 10.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}
```

| Өріс | Мағынасы |
|---|---|
| `type` | Қатенің жалпы санаты. Не істеу керегін осыдан анықтаңыз. |
| `code` | Нақты, тұрақты және машина оқитын себеп. Әр кодтың төменде бөлімі бар; `doc_url` соған сілтейді. |
| `message` | Әзірлеушіге көрсетуге немесе журналға жазуға болатын түсінікті түсіндірме. |
| `param` | Қате бар кіріс параметрі немесе тақырыбы. |
| `details` | Кіріс қателері үшін табылған барлық мәселе: `[{ "param", "message" }]`. |
| `request_id` | Бар болса, қатысты сұрау. |

Қатемен аяқталған шақыру үшін ақы алынбайды. Қабылданғаннан *кейін* сәтсіз аяқталған сұрау
`failed` күйінде қалады, сұрау нысанында `error: { "type", "code", "message" }` болады және қайтарым автоматты түрде жасалады.

## Түрлер

| Түрі | HTTP күйі | Не істеу керек |
|---|---|---|
| `invalid_request` | 400, 413 немесе 422 | Сұрауды түзетіңіз. Сол шақыруды қайталау қайтадан сәтсіз болады. |
| `authentication_error` | 401 | `Authorization: Bearer <key>` ішінде жарамды кілт жіберіңіз. |
| `permission_error` | 403 | Қажетті scope бар кілтті пайдаланыңыз. |
| `not_found` | 404 | Модель идентификаторын немесе сұрау идентификаторын тексеріңіз. |
| `insufficient_credits` | 402 | API теңгерімін толықтырыңыз (`top_up_url`). |
| `budget_exceeded` | 402 | Кілттің жеке бюджеті таусылды. Кілт иесінен оны арттыруды сұраңыз. |
| `conflict` | 409 | Ресурс бұл шақыруға мүмкіндік беретін күйде емес. |
| `rate_limited` | 429 | `Retry-After` секунд күтіп, кейін қайталаңыз. |
| `upstream_error` | 502 | Модель сервері сәтсіз аяқталды. Сол `Idempotency-Key` арқылы қайталауға болады; ақы алынбайды. |
| `service_unavailable` | 503 | API тоқтатылған немесе тәуелді қызмет істемей тұр. Кейін қайталаңыз. |
| `internal_error` | 500 | Бұл — біздің қатеміз. Қайталаңыз; жалғасса, уақыт пен `request_id` көрсетіп қолдауға хабарласыңыз. |

## Кодтар

### `invalid_request`

Жалпы қате құрылған сұрау (400).

### `invalid_json`

Дене жарамды JSON емес (400).

### `invalid_body`

Дене жарамды JSON, бірақ нысан емес; модель кірісі JSON нысаны болуы керек (400).

### `body_too_large`

Дене 16 MB-тан үлкен (413). Үлкен файлдарды жүктеп, орнына URL жіберіңіз ([Файлдар](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Сұрау параметрінің мәні қате: мысалы, `limit` 1–100 аралығынан тыс, `wait` сан емес, белгісіз `status` немесе `category`, не `storage` `permanent` / `temporary` мәндерінен басқа (400). Оның атауын `param` көрсетеді.

### `invalid_category`

`GET /openapi.json?category=` жоқ санатты көрсетеді (400). `GET https://api.doitong.com/v1/categories` оларды тізеді.

### `invalid_cursor`

Тізім шақыруындағы `cursor` осы тізімге тиесілі емес (400). Курсорсыз қайта бастаңыз.

### `invalid_idempotency_key`

`Idempotency-Key` тақырыбы бос немесе 255 таңбадан ұзын (400).

### `invalid_arguments`

MCP құралының шақыруында аргумент жоқ немесе қате пішімделген (тек MCP). Аргументті `param` көрсетеді.

### `invalid_input`

Модель кірісі тексеруден өтпеді (422): белгісіз параметр, міндетті параметрдің болмауы, қате түр, рұқсат етілген тізімнен немесе ауқымнан тыс мән, не канондық және native атаулардың әртүрлі мәндермен бірге берілуі. `param` бірінші қате параметрді, `details` барлығын көрсетеді. Ақы алынбайды.

### `unsupported_file`

Файл түрі қабылданбайды (422): мысалы, қолдау көрсетілмейтін кеңейтімі бар жүктеу немесе кеңейтімге сәйкес келмейтін `content_type`.

### `invalid_webhook_url`

`webhook_url` жалпыға қолжетімді `https://` URL емес (422). Жеке, жергілікті және жай `http://` мекенжайлары қабылданбайды.

### `missing_api_key`

Соңғы нүктеге API кілті қажет, бірақ ол жіберілмеген (401).

### `invalid_api_key`

Кілт белгісіз, қайтарылған немесе мерзімі өткен (401).

### `insufficient_scope`

Кілтте бұл шақыруға қажет scope жоқ (403), мысалы іске қосу үшін `models:run`, ал сұраулар мен теңгерімді оқу үшін `models:read`. [Аутентификация](https://doitong.com/developers/docs/authentication#scopes) бөлімін қараңыз.

### `account_disabled`

Тіркелгі жабылған немесе тоқтатылған (403). Оның кілттері енді жұмыс істемейді.

### `not_found`

Жол жоқ (404).

### `model_not_found`

Бұл идентификаторы бар жалпыға қолжетімді модель жоқ (404). Модельдерді `GET https://api.doitong.com/v1/models` арқылы тізіңіз.

### `request_not_found`

Тіркелгіңізде бұл идентификаторы бар сұрау жоқ (404). Басқа тіркелгілердің сұраулары ешқашан көрінбейді.

### `insufficient_credits`

Тіркелгінің **API теңгерімі** (API кредиттері, 1 000 API кредиті = 1 $ — Doitong қолданбаларының кредиттері емес) бұл шақыру бағасын жаппайды (402). Ақы алынбай тұрып жауап жіберіледі. Қате ішінде `top_up_url` бар; [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) арқылы қаражат қосып, қайталаңыз.

```json
{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
             "message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.com/developers/dashboard#balance",
             "top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }
```

### `budget_exceeded`

Шақыру API кілтінің жеке бюджетін API кредиттері бойынша асырады (402). Бюджетті кілт иесі белгілейді; ол арттырмайынша қайталау көмектеспейді.

### `conflict`

Шақыру ресурс күйімен қайшы (409).

### `idempotency_mismatch`

`Idempotency-Key` бұрын басқа денемен қолданылған (409). Жаңа операция үшін жаңа кілт қолданыңыз.

### `idempotency_in_progress`

Дәл сол `Idempotency-Key` бар сұрау қазір жасалуда (409). Оны алу үшін сәлден соң қайталаңыз.

### `request_active`

Сұрау әлі `queued` немесе `running`, сондықтан өшіретін файлдар әлі жоқ (409). Аяқталғаннан кейін өшіріңіз.

### `not_cancelable`

Сұрау `succeeded` немесе `failed` күйінде, сондықтан оны болдырмау мүмкін емес (409).

### `rate_limited`

Кілт ағымдағы терезеде тым көп сұрау жасады (429). `X-RateLimit-*` және `Retry-After` тақырыптарын қараңыз.

### `too_many_inflight`

Тіркелгіде қазірдің өзінде 10 `queued` немесе `running` сұрау бар (429). Келесісін біреуі аяқталған соң бастаңыз.

### `upstream_error`

Модель сервері сұрауды қабылдамады немесе сәтсіз аяқтады (іске қосуда 502 немесе сұрауда осы кодпен `failed`). API кредиттері қайтарылады. Егер сервер кірісті өзі қабылдамаса, шақыру оның хабарламасымен `422 invalid_input` қайтарады.

### `upstream_lost`

Модель сервері сұрауды енді білмейді, сондықтан нәтиже келмейді. Ол осы кодпен (типі `upstream_error`) `failed` күйіне өтіп, қайтарылады. Қайта іске қосыңыз.

### `timeout`

Сұрау шектен ұзақ орындалды (кескіндер үшін 15 минут, бейне үшін 60, өзгелері үшін 30) және тоқтатылды. Ол осы кодпен `failed` күйіне өтіп, қайтарылады.

### `service_unavailable`

API уақытша тоқтатылған немесе файл жүктеулері сияқты тәуелді қызмет істемей тұр (503). Кейін қайталаңыз.

### `internal_error`

Біздің жақта ақау болды (500). Қайталаңыз; жалғасса, қолдауға хабарласыңыз.

### `charge_failed`

Ішкі ақауға байланысты тіркелгіден ақы алу мүмкін болмады (500). Сұрау `failed` деп белгіленді; ақша алынбады. Қайталаңыз.

### `pricing_unavailable`

Модель бағасы бапталмаған, сондықтан оны қазір есептеу немесе іске қосу мүмкін емес (500).