# Mga Error

Ang bawat endpoint ay nabibigo sa parehong paraan: isang HTTP status at isang JSON envelope.

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

| Field | Kahulugan |
|---|---|
| `type` | Pangkalahatang uri ng error. Dito batay kung ano ang gagawin. |
| `code` | Eksaktong dahilan, stable at nababasa ng machine. May seksyon sa ibaba ang bawat code; dito nakaturo ang `doc_url`. |
| `message` | Paliwanag na mababasa ng tao, ligtas i-log o ipakita sa isang developer. |
| `param` | Ang input parameter o header na may problema, kung mayroon. |
| `details` | Para sa mga input error, lahat ng nakitang problema: `[{ "param", "message" }]`. |
| `request_id` | Ang kahilingan na tinutukoy nito, kung mayroon. |

Walang sinisingil para sa call na nagbabalik ng error. Ang kahilingang nabigo *pagkatapos* itong tanggapin ay nananatiling may status na
`failed`, may `error: { "type", "code", "message" }` sa request object, at awtomatikong nire-refund.

## Mga Uri

| Uri | HTTP status | Gagawin |
|---|---|---|
| `invalid_request` | 400, 413 o 422 | Ayusin ang kahilingan. Muli itong mabibigo kung uulitin ang parehong call. |
| `authentication_error` | 401 | Magpadala ng valid na key sa `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Gumamit ng key na may kinakailangang scope. |
| `not_found` | 404 | Suriin ang modelo id o kahilingan id. |
| `insufficient_credits` | 402 | Magdagdag ng balanse ng API (`top_up_url` sa error). |
| `budget_exceeded` | 402 | Naubos ang sariling badyet ng key. Panghuli: hilingin sa may-ari ng key na itaas ito. |
| `conflict` | 409 | Wala sa estado ang resource na nagpapahintulot sa call na ito. |
| `rate_limited` | 429 | Maghintay ng `Retry-After` segundo, pagkatapos ay subukang muli. |
| `upstream_error` | 502 | Nabigo ang backend ng modelo. Ligtas subukang muli gamit ang parehong `Idempotency-Key`: tatakbo itong muli; hindi ka siningil. |
| `service_unavailable` | 503 | Naka-pause ang API o hindi gumagana ang isang dependency. Subukang muli mamaya. |
| `internal_error` | 500 | Bug namin ito. Subukang muli; kung magpatuloy, makipag-ugnayan sa support kasama ang oras at `request_id`. |

## Mga Code

### `invalid_request`

Pangkalahatang malformed na kahilingan (400).

### `invalid_json`

Hindi valid na JSON ang body (400).

### `invalid_body`

Valid na JSON ang body ngunit hindi ito isang object; dapat JSON object ang input ng modelo (400).

### `body_too_large`

Mas malaki sa 16 MB ang body (413). Mag-upload ng malalaking file at sa halip ay ipasa ang URL ng mga ito (tingnan ang [Files](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Mali ang value ng isang query parameter, halimbawa, ang `limit` ay wala sa 1 hanggang 100, ang `wait` ay hindi numero, isang hindi kilalang
`status` o `category`, o ang `storage` ay hindi `permanent` / `temporary` (400). Tinutukoy ito ng `param`.

### `invalid_category`

Ang `GET /openapi.json?category=` ay tumutukoy sa kategoryang wala (400). Inililista ng `GET https://api.doitong.ru/v1/categories` ang mga ito.

### `invalid_cursor`

Hindi kabilang sa listahang ito ang `cursor` ng list call (400). Magsimulang muli nang walang cursor.

### `invalid_idempotency_key`

Walang laman ang `Idempotency-Key` header o mas mahaba ito sa 255 character (400).

### `invalid_arguments`

May nawawala o malformed na argument ang isang MCP tool call (MCP only). Tinutukoy ng `param` ang argument.

### `invalid_input`

Hindi pumapasa sa validation ang input ng modelo (422): hindi kilalang parameter (iminumungkahi ng message ang pinakamalapit na valid na pangalan),
walang kinakailangang parameter, maling type, value na wala sa pinapahintulutang listahan o range, o parehong ibinigay ang canonical at
native na pangalan na magkaiba ang value. Ang `param` ang unang problemadong parameter at inililista ng `details` ang lahat ng mga ito.
Walang sinisingil.

### `unsupported_file`

May type ang isang file na hindi namin tinatanggap (422), halimbawa, upload na may hindi suportadong extension, o `content_type`
na hindi tugma sa extension.

### `invalid_webhook_url`

Hindi pampublikong `https://` URL ang `webhook_url` (422). Tinatanggihan ang mga pribado, lokal at simpleng `http://` address.

### `missing_api_key`

Nangangailangan ng API key ang endpoint ngunit walang ipinadala (401).

### `invalid_api_key`

Hindi kilala, binawi o nag-expire ang key (401).

### `insufficient_scope`

Walang scope ang key na kailangan ng call na ito (403), halimbawa, `models:run` para sa run, o `models:read` para magbasa ng
mga kahilingan at balanse. Tingnan ang [Authentication](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Sarado o suspendido ang account (403). Hindi na gumagana ang mga key nito.

### `not_found`

Hindi umiiral ang path (404).

### `model_not_found`

Walang pampublikong modelo na may ganitong id (404). Maglista ng mga modelo gamit ang `GET https://api.doitong.ru/v1/models`.

### `request_not_found`

Walang kahilingan na may ganitong id sa iyong account (404). Hindi kailanman nakikita ang mga kahilingan ng ibang account.

### `insufficient_credits`

Hindi sapat ang **balanse ng API** ng account (kredito ng API, 1,000 kredito ng API = $1 — hindi ang kredito ng Doitong apps) para sa
presyo ng call na ito (402). Ipinapadala ang response bago maningil. May `top_up_url` ang error; magdagdag ng pera
sa [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance) at subukang muli.

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

Malalampasan ng call ang sariling badyet ng API key sa kredito ng API (402). Itinatakda ng may-ari ng key ang badyet; walang
maitutulong ang muling pagsubok hanggang hindi ito itinataas ng may-ari.

### `conflict`

Sumasalungat ang call sa kasalukuyang estado ng resource (409).

### `idempotency_mismatch`

Nagamit na ang `Idempotency-Key` sa ibang body (409). Gumamit ng bagong key para sa bagong operasyon.

### `idempotency_in_progress`

Kasalukuyang ginagawa ang isang kahilingan na may parehong `Idempotency-Key` (409). Maghintay sandali at subukang muli para makuha ito.

### `request_active`

Nasa `queued` o `running` pa ang kahilingan, kaya wala pa itong file na maaaring tanggalin (409). Tanggalin ang mga ito kapag natapos na.

### `not_cancelable`

Nasa `succeeded` o `failed` na ang kahilingan at hindi na maaaring kanselahin (409).

### `rate_limited`

Napakaraming kahilingan ang ginawa ng key sa kasalukuyang window (429). Tingnan ang `X-RateLimit-*` at `Retry-After` headers.

### `too_many_inflight`

Mayroon nang 10 kahilingan ang account na `queued` o `running` (429). Simulan ang susunod kapag natapos ang isa sa mga ito.

### `upstream_error`

Tinanggihan o hindi naproseso ng backend ng modelo ang kahilingan (502 sa run, o `failed` na may ganitong code sa kahilingan). Nire-refund ang
kredito ng API. Kung mismong backend ang tumanggi sa input, ibinabalik ng call ang `422 invalid_input` kasama ang message nito.

### `upstream_lost`

Hindi na alam ng backend ng modelo ang kahilingan, kaya wala nang resultang darating. Magtatapos ito bilang `failed` na may ganitong code
(type na `upstream_error`) at ire-refund. Patakbuhin itong muli.

### `timeout`

Tumakbo ang kahilingan nang mas matagal sa limit nito (15 minuto para sa mga larawan, 60 para sa video, 30 kung hindi) at itinigil. Magtatapos ito bilang
`failed` na may ganitong code at ire-refund.

### `service_unavailable`

Pansamantalang naka-pause ang API, o hindi gumagana ang dependency gaya ng mga upload ng file (503). Subukang muli mamaya.

### `internal_error`

May nasira sa panig namin (500). Subukang muli; kung magpatuloy, makipag-ugnayan sa support.

### `charge_failed`

Hindi masingil ang account dahil sa internal na problema (500). Minarkahan ang kahilingan bilang `failed`; walang kinuha. Subukang muli.

### `pricing_unavailable`

Hindi naka-configure ang presyo ng modelo, kaya hindi ito ma-quote o mapatakbo sa ngayon (500).