# Żbalji

Kull endpoint ifalli bl-istess mod: status HTTP u envelop JSON wieħed.

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

| Qasam | Tifsira |
|---|---|
| `type` | Klassifikazzjoni wiesgħa tal-iżball. Iddeċiedi x’għandek tagħmel minn dan. |
| `code` | Ir-raġuni eżatta, stabbli u li tinqara mill-magni. Kull kodiċi għandu taqsima hawn taħt; `doc_url` jorbot magħha. |
| `message` | Spjegazzjoni li tinqara mill-bniedem, sigura biex tiġi rreġistrata jew murija lil żviluppatur. |
| `param` | Il-parametru tal-input jew il-header li kkawża l-problema, jekk ikun hemm wieħed. |
| `details` | Għal żbalji tal-input, kull problema misjuba: `[{ "param", "message" }]`. |
| `request_id` | It-talba li tirreferi għaliha, jekk teżisti. |

Ma jitħallas xejn għal sejħa li tirritorna żball. Talba li tfalli *wara* li tkun ġiet aċċettata żżomm l-istatus
`failed`, ikollha `error: { "type", "code", "message" }` fuq l-oġġett tat-talba, u tirċievi rifużjoni awtomatikament.

## Tipi

| Tip | Status HTTP | X’għandek tagħmel |
|---|---|---|
| `invalid_request` | 400, 413 jew 422 | Irranġa t-talba. Jekk terġa’ tibgħat l-istess sejħa, terġa’ tfalli. |
| `authentication_error` | 401 | Ibgħat ċavetta valida f’`Authorization: Bearer <key>`. |
| `permission_error` | 403 | Uża ċavetta bl-ambitu meħtieġ. |
| `not_found` | 404 | Iċċekkja l-ID tal-mudell jew talba. |
| `insufficient_credits` | 402 | Agħmel top-up tal-bilanċ tal-API (`top_up_url` fl-iżball). |
| `budget_exceeded` | 402 | Il-baġit tal-kompost innifsu taċ-ċavetta ntuża kollu. Finali: staqsi lil sid iċ-ċavetta biex iżidu. |
| `conflict` | 409 | Ir-riżorsa mhijiex fi stat li jippermetti din is-sejħa. |
| `rate_limited` | 429 | Stenna `Retry-After` sekondi, imbagħad erġa’ pprova. |
| `upstream_error` | 502 | Il-backend tal-mudell falla. Huwa sigur li terġa’ tipprova bl-istess `Idempotency-Key`: terġa’ titħaddem; ma tħallastx. |
| `service_unavailable` | 503 | L-API waqfet temporanjament jew dipendenza mhijiex disponibbli. Erġa’ pprova aktar tard. |
| `internal_error` | 500 | Żball min-naħa tagħna. Erġa’ pprova; jekk jibqa’ jseħħ, ikkuntattja l-appoġġ bil-ħin u `request_id`. |

## Kodiċijiet

### `invalid_request`

Talba ġenerika fformattjata ħażin (400).

### `invalid_json`

Il-body mhuwiex JSON validu (400).

### `invalid_body`

Il-body huwa JSON validu iżda mhuwiex oġġett; l-input tal-mudell irid ikun oġġett JSON (400).

### `body_too_large`

Il-body huwa akbar minn 16 MB (413). Tella’ fajls kbar u għaddi l-URL tagħhom minflok (ara [Fajls](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Parametru ta’ query għandu valur żbaljat, pereżempju `limit` barra minn 1 sa 100, `wait` mhux numru, `status` jew `category` mhux magħruf, jew `storage` għajr `permanent` / `temporary` (400). `param` jidentifikah.

### `invalid_category`

`GET /openapi.json?category=` isem kategorija li ma teżistix (400). `GET https://api.doitong.ru/v1/categories` jelenkahom.

### `invalid_cursor`

Il-`cursor` ta’ sejħa ta’ lista ma jappartjenix lil din il-lista (400). Ibda mill-ġdid mingħajr cursor.

### `invalid_idempotency_key`

Il-header `Idempotency-Key` huwa vojt jew itwal minn 255 karattru (400).

### `invalid_arguments`

Sejħa ta’ għodda MCP għandha argument nieqes jew ifformattjat ħażin (MCP biss). `param` jidentifika l-argument.

### `invalid_input`

L-input tal-mudell ma jgħaddix mill-validazzjoni (422): parametru mhux magħruf (il-messaġġ jissuġġerixxi l-eqreb isem validu), parametru meħtieġ nieqes, tip żbaljat, valur barra mil-lista jew mill-firxa permessa, jew kemm l-isem kanoniku kif ukoll dak nattiv mogħtija b’valuri differenti. `param` huwa l-ewwel parametru problematiku u `details` jelenka kollha. Ma jitħallas xejn.

### `unsupported_file`

Fajl għandu tip li ma naċċettawx (422), pereżempju upload b’estensjoni mhux appoġġjata, jew `content_type` li ma jaqbilx mal-estensjoni.

### `invalid_webhook_url`

`webhook_url` mhuwiex URL pubbliku `https://` (422). Indirizzi privati, lokali u sempliċi `http://` jiġu rrifjutati.

### `missing_api_key`

L-endpoint jeħtieġ ċavetta API u ma ntbagħtet l-ebda waħda (401).

### `invalid_api_key`

Iċ-ċavetta mhijiex magħrufa, ġiet revokata jew skadiet (401).

### `insufficient_scope`

Iċ-ċavetta m’għandhiex l-ambitu meħtieġ minn din is-sejħa (403), pereżempju `models:run` biex titħaddem, jew `models:read` biex jinqraw it-talbiet u l-bilanċ. Ara [Awtentikazzjoni](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Il-kont ingħalaq jew ġie sospiż (403). Iċ-ċwievet tiegħu ma jibqgħux jaħdmu.

### `not_found`

Il-path ma jeżistix (404).

### `model_not_found`

L-ebda mudell pubbliku ma għandu dan l-ID (404). Elenka l-mudelli b’`GET https://api.doitong.ru/v1/models`.

### `request_not_found`

Ma teżisti l-ebda talba b’dan l-ID fil-kont tiegħek (404). It-talbiet ta’ kontijiet oħra qatt ma jkunu viżibbli.

### `insufficient_credits`

Il-**bilanċ tal-API** tal-kont (krediti tal-API, 1,000 krediti tal-API = $1 — mhux il-krediti tal-apps ta’ Doitong) ma jkoprix il-prezz ta’ din is-sejħa (402). Ir-rispons jintbagħat qabel ma jitħallas xi ħaġa. L-iżball għandu `top_up_url`; żid il-flus fuq [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance) u erġa’ pprova.

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

Is-sejħa taqbeż il-baġit proprju taċ-ċavetta API fi krediti tal-API (402). Il-baġit jiġi stabbilit minn sid iċ-ċavetta; li terġa’ tipprova ma jgħinx sakemm iżiduh.

### `conflict`

Is-sejħa tikkonfliġġi mal-istat attwali tar-riżorsa (409).

### `idempotency_mismatch`

`Idempotency-Key` diġà ntuża b’body differenti (409). Uża ċavetta ġdida għal operazzjoni ġdida.

### `idempotency_in_progress`

Talba bl-istess `Idempotency-Key` qed tinħoloq bħalissa (409). Erġa’ pprova wara mument biex tiksebha.

### `request_active`

It-talba għadha `queued` jew `running`, għalhekk għad m’għandhiex fajls x’tħassar (409). Ħassarhom wara li tispiċċa.

### `not_cancelable`

It-talba diġà hija `succeeded` jew `failed` u ma tistax tiġi kkanċellata (409).

### `rate_limited`

Iċ-ċavetta għamlet wisq talbiet fit-tieqa attwali (429). Ara l-headers `X-RateLimit-*` u `Retry-After`.

### `too_many_inflight`

Il-kont diġà għandu 10 talbiet `queued` jew `running` (429). Ibda dik li jmiss meta waħda minnhom tispiċċa.

### `upstream_error`

Il-backend tal-mudell irrifjuta jew falla fit-talba (502 waqt it-tħaddim, jew `failed` b’dan il-kodiċi fuq it-talba). Il-krediti tal-API jiġu rifużi. Jekk il-backend innifsu rrifjuta l-input, is-sejħa tirritorna `422 invalid_input` bil-messaġġ tagħha minflok.

### `upstream_lost`

Il-backend tal-mudell m’għadux jaf bit-talba, għalhekk qatt mhu se jasal riżultat. Tispiċċa bħala `failed` b’dan il-kodiċi (tip `upstream_error`) u tirċievi rifużjoni. Erġa’ ħaddimha.

### `timeout`

It-talba damet aktar mil-limitu tagħha (15-il minuta għall-immaġnijiet, 60 għall-vidjo, 30 għal kull ħaġa oħra) u twaqqfet. Tispiċċa bħala `failed` b’dan il-kodiċi u tirċievi rifużjoni.

### `service_unavailable`

L-API waqfet temporanjament, jew dipendenza bħal uploads ta’ fajls mhijiex disponibbli (503). Erġa’ pprova aktar tard.

### `internal_error`

Xi ħaġa marret ħażin min-naħa tagħna (500). Erġa’ pprova; jekk jibqa’ jseħħ, ikkuntattja l-appoġġ.

### `charge_failed`

Il-kont ma setax jiġi ċċarġjat minħabba problema interna (500). It-talba tiġi mmarkata `failed`; ma ttieħed xejn. Erġa’ pprova.

### `pricing_unavailable`

Il-prezz tal-mudell mhuwiex ikkonfigurat, għalhekk bħalissa ma jistax jiġi kkwotat jew imħaddem (500).