# Ngā hapa

He ōrite te rahunga o ia pito API: he tūnga HTTP me tētahi kōpaki 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"
  }
}
```

| Āpure | Tikanga |
|---|---|
| `type` | Te akomanga whānui o te hapa. Mā konei e whakatau ai te mahi. |
| `code` | Te take pūmau, ka taea e te mīhini te pānui. He wāhanga kei raro mō ia waehere; ka hono a `doc_url` ki reira. |
| `message` | He whakamārama mā te tangata, he haumaru te tuhi ki te rākau, te whakaatu rānei ki tētahi kaiwhakawhanake. |
| `param` | Te tawhā tāuru, te pane rānei i hapa, mēnā he mea pēnei. |
| `details` | Mō ngā hapa tāuru, ngā raru katoa i kitea: `[{ "param", "message" }]`. |
| `request_id` | Te tono e pā ana, mēnā kei reira. |

Kāore he utu mō tētahi karanga ka whakahoki hapa. Ko tētahi tono ka rahua *whai muri* i te whakaaetanga, ka mau tonu ki te tūnga
`failed`, ka mau i te `error: { "type", "code", "message" }` ki te ahanoa tono, ā, ka whakahokia aunoatia te pūtea.

## Ngā momo

| Momo | Tūnga HTTP | Me aha |
|---|---|---|
| `invalid_request` | 400, 413 or 422 | Whakatikahia te tono. Ka rahua anō te karanga ōrite. |
| `authentication_error` | 401 | Tukuna he kī tika ki `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Whakamahia he kī kei a ia te whānuitanga e hiahiatia ana. |
| `not_found` | 404 | Tirohia te id tauira, te id tono rānei. |
| `insufficient_credits` | 402 | Tāpirihia pūtea ki te toenga API (`top_up_url` kei roto i te hapa). |
| `budget_exceeded` | 402 | Kua pau te pūtea ake o te kī. Whakamutunga: tonoa te rangatira o te kī kia whakanuia. |
| `conflict` | 409 | Kāore te rauemi i te tūnga e whakaahei ana i tēnei karanga. |
| `rate_limited` | 429 | Tatari `Retry-After` hēkona, kātahi ka tuku anō. |
| `upstream_error` | 502 | I rahua te pūnaha tuarongo o te tauira. He haumaru te tuku anō me te `Idempotency-Key` ōrite: ka rere anō; kāore he utu. |
| `service_unavailable` | 503 | Kua whakatā te API, kua kore rānei tētahi whakawhirinakitanga e wātea ana. Tukua anō ā muri ake. |
| `internal_error` | 500 | He hapa nā mātou. Tukua anō; ki te mau tonu, whakapā atu ki te tautoko me te wā me `request_id`. |

## Ngā waehere

### `invalid_request`

He tono hē te hanga (400).

### `invalid_json`

Ehara te tinana i te JSON tika (400).

### `invalid_body`

He JSON tika te tinana, engari ehara i te ahanoa; me noho te tāuru tauira hei ahanoa JSON (400).

### `body_too_large`

He nui ake te tinana i te 16 MB (413). Tukuna ngā kōnae nui, ka tukuna kē tō rātou URL (tirohia [Ngā kōnae](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

He hē te uara o tētahi tawhā uiui, hei tauira ko `limit` kei waho i te 1 ki te 100, ko `wait` ehara i te tau, he `status`, `category` rānei kāore i te mōhiotia,
he `storage` kē atu i `permanent` / `temporary` (400). Mā `param` e tohu.

### `invalid_category`

E tohu ana a `GET /openapi.json?category=` ki tētahi kāwai kāore e tū ana (400). Mā `GET https://api.doitong.ru/v1/categories` e whakarārangi.

### `invalid_cursor`

Kāore te `cursor` o tētahi karanga rārangi nō tēnei rārangi (400). Tīmata anō me te kore cursor.

### `invalid_idempotency_key`

He putua te pane `Idempotency-Key`, he roa ake rānei i te 255 pūāhua (400).

### `invalid_arguments`

He hapa, he hē rānei te tautohenga o tētahi karanga taputapu MCP (MCP anake). Mā `param` e tohu te tautohenga.

### `invalid_input`

Kāore te tāuru tauira e tutuki i te whakamana (422): he tawhā kāore i te mōhiotia (ka tohu te karere i te ingoa tika e tino tata ana),
he tawhā e hiahiatia ana kua ngaro, he momo hē, he uara kei waho i te rārangi, i te awhe rānei e whakaaetia ana, he ingoa tōtika me te ingoa taketake rānei kua hoatu me ngā uara rerekē. Ko `param` te tawhā tuatahi i hapa, ā, mā `details` ngā mea katoa e whakarārangi.
Kāore he utu.

### `unsupported_file`

He momo kāore mātou e whakaae ana tō tētahi kōnae (422), hei tauira he toronga kāore e tautokona ana, he `content_type` rānei kāore e hāngai ana ki te toronga.

### `invalid_webhook_url`

Ehara a `webhook_url` i te URL tūmatanui `https://` (422). Ka whakahēngia ngā wāhitau tūmataiti, ā-rohe, me te `http://` māori.

### `missing_api_key`

Me whai kī API te pito API, engari kāore he mea i tukuna (401).

### `invalid_api_key`

Kāore te kī i te mōhiotia, kua whakakorehia, kua pau rānei (401).

### `insufficient_scope`

Kāore i te kī te whānuitanga e hiahiatia ana mō tēnei karanga (403), hei tauira `models:run` mō te whakahaere, `models:read` rānei hei pānui i ngā tono me te toenga. Tirohia [Te whakamotuhēhēnga](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Kua katia, kua whakatārewatia rānei te pūkete (403). Kāore āna kī e mahi anō.

### `not_found`

Kāore taua ara e tū ana (404).

### `model_not_found`

Kāore he tauira tūmatanui kei taua id (404). Whakarārangihia ngā tauira mā `GET https://api.doitong.ru/v1/models`.

### `request_not_found`

Kāore he tono kei tō pūkete me taua id (404). Kāore rawa e kitea ngā tono a ētahi atu pūkete.

### `insufficient_credits`

Kāore te **toenga API** o te pūkete (whiwhinga API, 1,000 whiwhinga API = $ 1 — ehara i ngā whiwhinga o ngā taupānga Doitong) e ea i te utu o tēnei karanga (402). Ka tukuna te whakautu i mua i te tangohanga utu. Kei roto i te hapa a `top_up_url`; tāpirihia he pūtea ki [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance), ka tuku anō.

```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.ru/developers/dashboard#balance",
             "top_up_url": "https://doitong.ru/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }
```

### `budget_exceeded`

Ka hipa te karanga i te pūtea ake o te kī API i roto i ngā whiwhinga API (402). Nā te rangatira o te kī te pūtea i whakarite; kāore te tuku anō e āwhina kia whakanuia ra anō.

### `conflict`

E taupatupatu ana te karanga ki te tūnga o nāianei o te rauemi (409).

### `idempotency_mismatch`

Kua whakamahia kētia te `Idempotency-Key` me tētahi tinana rerekē (409). Whakamahia he kī hou mō tētahi mahi hou.

### `idempotency_in_progress`

Kei te waihangahia ināianei tētahi tono me te `Idempotency-Key` ōrite (409). Tukua anō ākuanei kia whiwhi ai.

### `request_active`

Kei te `queued`, kei te `running` rānei te tono, nō reira kāore anō ōna kōnae hei muku (409). Mukua ā muri i tōna mutunga.

### `not_cancelable`

Kua `succeeded`, kua `failed` rānei te tono, ā, kāore e taea te whakakore (409).

### `rate_limited`

He nui rawa ngā tono a te kī i tēnei wāhanga (429). Tirohia ngā pane `X-RateLimit-*` me `Retry-After`.

### `too_many_inflight`

Kua 10 ngā tono `queued`, `running` rānei a te pūkete (429). Tīmatahia te mea whai muri ina mutu tētahi.

### `upstream_error`

I whakahē, i rahua rānei te tono e te pūnaha tuarongo o te tauira (502 i te whakahaere, `failed` me tēnei waehere rānei i te tono). Ka whakahokia ngā whiwhinga API. Ki te whakahē te pūnaha tuarongo i te tāuru ake, ka whakahoki te karanga i `422 invalid_input` me tana karere.

### `upstream_lost`

Kua kore te pūnaha tuarongo e mōhio ki te tono, nō reira kore rawa he hua e tae mai. Ka mutu hei `failed` me tēnei waehere (momo `upstream_error`), ā, ka whakahokia te pūtea. Whakahaerehia anō.

### `timeout`

He roa ake te whakahaere o te tono i tōna rohe (15 meneti mō ngā atahanga, 60 mō te ataata, 30 mō ērā atu), ā, ka whakamutua. Ka mutu hei `failed` me tēnei waehere, ā, ka whakahokia te pūtea.

### `service_unavailable`

Kua whakatā mō te wā poto te API, kua kore rānei tētahi whakawhirinakitanga pēnei i te tuku kōnae e wātea ana (503). Tukua anō ā muri ake.

### `internal_error`

Kua pakaru tētahi mea i tō mātou taha (500). Tukua anō; ki te mau tonu, whakapā atu ki te tautoko.

### `charge_failed`

Kāore i taea te tango pūtea i te pūkete nā tētahi raru ā-roto (500). Ka tohua te tono hei `failed`; kāore he mea i tangohia. Tukua anō.

### `pricing_unavailable`

Kāore te utu o te tauira i te whirihora, nō reira kāore e taea te whakahua utu, te whakahaere rānei ināianei (500).