# Hitilafu

Kila endpoint hushindwa kwa njia ileile: hali ya HTTP na bahasha moja ya 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"
  }
}
```

| Sehemu | Maana |
|---|---|
| `type` | Aina pana ya hitilafu. Amua cha kufanya kwa kutumia hii. |
| `code` | Sababu kamili, thabiti na inayosomeka na mashine. Kila msimbo una sehemu hapa chini; `doc_url` inaelekeza kwake. |
| `message` | Maelezo yanayosomeka na binadamu, salama kuyaandika kwenye logi au kumwonyesha msanidi. |
| `param` | Kigezo cha ingizo au kichwa chenye tatizo, ikiwa kipo. |
| `details` | Kwa hitilafu za ingizo, kila tatizo lililopatikana: `[{ "param", "message" }]`. |
| `request_id` | Ombi linalohusika, ikiwa lipo. |

Hakuna kinachotozwa kwa simu inayorejesha hitilafu. Ombi linaloshindwa *baada* ya kukubaliwa hubaki na hali
`failed`, huwa na `error: { "type", "code", "message" }` kwenye kitu cha ombi, na hurejeshewa fedha kiotomatiki.

## Aina

| Aina | Hali ya HTTP | Cha kufanya |
|---|---|---|
| `invalid_request` | 400, 413 au 422 | Rekebisha ombi. Kujaribu tena simu ileile kutashindwa tena. |
| `authentication_error` | 401 | Tuma ufunguo halali katika `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Tumia ufunguo wenye scope inayohitajika. |
| `not_found` | 404 | Kagua kitambulisho cha modeli au cha ombi. |
| `insufficient_credits` | 402 | Ongeza salio la API (`top_up_url` kwenye hitilafu). |
| `budget_exceeded` | 402 | Bajeti ya ufunguo yenyewe imetumika. Mwisho: mwombe mmiliki wa ufunguo aiongeze. |
| `conflict` | 409 | Rasilimali haiko katika hali inayoruhusu simu hii. |
| `rate_limited` | 429 | Subiri sekunde za `Retry-After`, kisha jaribu tena. |
| `upstream_error` | 502 | Backend ya modeli imeshindwa. Ni salama kujaribu tena kwa `Idempotency-Key` ileile: itaendeshwa tena; hukutozwa. |
| `service_unavailable` | 503 | API imesitishwa au utegemezi haupatikani. Jaribu tena baadaye. |
| `internal_error` | 500 | Hitilafu yetu. Jaribu tena; ikiendelea, wasiliana na usaidizi ukiweka muda na `request_id`. |

## Misimbo

### `invalid_request`

Ombi la jumla lenye muundo usio sahihi (400).

### `invalid_json`

Mwili si JSON halali (400).

### `invalid_body`

Mwili ni JSON halali lakini si kitu; ingizo la modeli lazima liwe kitu cha JSON (400).

### `body_too_large`

Mwili ni mkubwa kuliko 16 MB (413). Pakia faili kubwa na upitishe URL yake badala yake (tazama [Faili](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Kigezo cha query kina thamani isiyo sahihi, kwa mfano `limit` iliyo nje ya 1 hadi 100, `wait` isiyo nambari, `status` au
`category` isiyojulikana, au `storage` iliyo tofauti na `permanent` / `temporary` (400). `param` hukitaja.

### `invalid_category`

`GET /openapi.json?category=` inataja kategoria ambayo haipo (400). `GET https://api.doitong.com/v1/categories` huziorodhesha.

### `invalid_cursor`

`cursor` ya simu ya orodha si ya orodha hii (400). Anza tena bila cursor.

### `invalid_idempotency_key`

Kichwa `Idempotency-Key` ni tupu au kina zaidi ya vibambo 255 (400).

### `invalid_arguments`

Simu ya zana ya MCP ina hoja iliyokosekana au yenye muundo usio sahihi (MCP pekee). `param` hutaja hoja hiyo.

### `invalid_input`

Ingizo la modeli halipitishi uthibitishaji (422): kigezo kisichojulikana (ujumbe hupendekeza jina halali lililo karibu),
kigezo cha lazima kilichokosekana, aina isiyo sahihi, thamani iliyo nje ya orodha au masafa yanayoruhusiwa, au jina la
kikanuni na jina asilia yote yamepewa thamani tofauti. `param` ni kigezo cha kwanza chenye tatizo na `details` huorodhesha vyote.
Hakuna kinachotozwa.

### `unsupported_file`

Faili ina aina tusiyokubali (422), kwa mfano upakiaji wenye kiendelezi kisichotumika, au `content_type`
isiyolingana na kiendelezi.

### `invalid_webhook_url`

`webhook_url` si URL ya umma ya `https://` (422). Anwani za faragha, za ndani na za kawaida za `http://` hukataliwa.

### `missing_api_key`

Endpoint inahitaji ufunguo wa API na hakuna uliotumwa (401).

### `invalid_api_key`

Ufunguo haujulikani, umebatilishwa au umeisha muda (401).

### `insufficient_scope`

Ufunguo hauna scope inayohitajika na simu hii (403), kwa mfano `models:run` kwa kuendesha, au `models:read` kusoma
maombi na salio. Tazama [Uthibitishaji](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Akaunti imefungwa au imesimamishwa (403). Funguo zake hazifanyi kazi tena.

### `not_found`

Njia haipo (404).

### `model_not_found`

Hakuna modeli ya umma yenye kitambulisho hiki (404). Orodhesha modeli kwa `GET https://api.doitong.com/v1/models`.

### `request_not_found`

Hakuna ombi lenye kitambulisho hiki katika akaunti yako (404). Maombi ya akaunti nyingine hayaonekani kamwe.

### `insufficient_credits`

**Salio la API** la akaunti (krediti za API, salio za API 1,000 = $ 1 — si krediti za programu za Doitong) halitoshi kugharamia
bei ya simu hii (402). Jibu hutumwa kabla ya chochote kutozwa. Hitilafu ina `top_up_url`; ongeza fedha kwenye
[https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) na ujaribu tena.

```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`

Simu ingezidi bajeti ya ufunguo wa API yenyewe kwa krediti za API (402). Bajeti huwekwa na mmiliki wa ufunguo; kujaribu tena hakutasaidia hadi aiongeze.

### `conflict`

Simu inakinzana na hali ya sasa ya rasilimali (409).

### `idempotency_mismatch`

`Idempotency-Key` ilishatumika na mwili tofauti (409). Tumia ufunguo mpya kwa operesheni mpya.

### `idempotency_in_progress`

Ombi lenye `Idempotency-Key` hiyo linaundwa sasa (409). Jaribu tena baada ya muda mfupi ili kulipata.

### `request_active`

Ombi bado ni `queued` au `running`, hivyo bado halina faili za kufuta (409). Zifute likikamilika.

### `not_cancelable`

Ombi tayari ni `succeeded` au `failed` na haliwezi kughairiwa (409).

### `rate_limited`

Ufunguo ulifanya maombi mengi mno katika kipindi cha sasa (429). Tazama vichwa `X-RateLimit-*` na `Retry-After`.

### `too_many_inflight`

Akaunti tayari ina maombi 10 yaliyo `queued` au `running` (429). Anzisha linalofuata moja likikamilika.

### `upstream_error`

Backend ya modeli ilikataa au imeshindwa kushughulikia ombi (502 wakati wa kuendesha, au `failed` yenye msimbo huu kwenye ombi). Krediti za API zimerejeshewa fedha. Ikiwa backend yenyewe ilikataa ingizo, simu hurejesha `422 invalid_input` yenye ujumbe wake.

### `upstream_lost`

Backend ya modeli haijui tena ombi, kwa hiyo matokeo hayatawasili kamwe. Huisha kama `failed` yenye msimbo huu
(aina `upstream_error`) na hurejeshewa fedha. Liendeshe tena.

### `timeout`

Ombi liliendeshwa zaidi ya kikomo chake (dakika 15 kwa picha, 60 kwa video, 30 vinginevyo) na likasimamishwa. Huisha kama
`failed` yenye msimbo huu na hurejeshewa fedha.

### `service_unavailable`

API imesitishwa kwa muda, au utegemezi kama upakiaji wa faili haupatikani (503). Jaribu tena baadaye.

### `internal_error`

Kuna kitu kimeharibika upande wetu (500). Jaribu tena; ikiendelea, wasiliana na usaidizi.

### `charge_failed`

Akaunti haikuweza kutozwa kwa sababu ya tatizo la ndani (500). Ombi limewekwa kuwa `failed`; hakuna kilichochukuliwa. Jaribu tena.

### `pricing_unavailable`

Bei ya modeli haijawekwa, kwa hiyo haiwezi kukadiriwa au kuendeshwa kwa sasa (500).