# Greškipen

Sa konak endpointura keren avro aynı dromesa: HTTP status thaj jekh 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 | So značinel |
|---|---|
| `type` | Široko klasa e greškipnaski. Kadale phenel so te keres. |
| `code` | Precizno razlog, stabilno thaj manušeske čitavipen. Sako kodo si lesko sekcija tele; `doc_url` sikavel leste. |
| `message` | Manušeske čitavipen e objašnjenje, sigurno te loginel vaj te sikavel developereske. |
| `param` | Inputo parametro vaj header, savo si bilačho, kana si jekh. |
| `details` | Vaš inputo greški, sako problem savo arakhlam: `[{ "param", "message" }]`. |
| `request_id` | O mangipen pal soste džal, kana si les. |

Nič na ovel lilăslo vaš jekh mangipen savo anel greškipen. Jekh mangipen savo našľol *palal* so sas prihvatime ačhol statusesa
`failed`, ingerel `error: { "type", "code", "message" }` pe objektosko mangipen, thaj iren pes avtomatikane.

## Tipura

| Tip | HTTP status | So te keres |
|---|---|---|
| `invalid_request` | 400, 413 vaj 422 | Poprav o mangipen. Te palem bičhaves sa kodo, palem našľola. |
| `authentication_error` | 401 | Bičhav validno API klidin andro `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Istinav klidin saves si e potrebno scope. |
| `not_found` | 404 | Dik o modelo id vaj o mangipnasko id. |
| `insufficient_credits` | 402 | Ker pheripen pe API balanso (`top_up_url` andro greškipen). |
| `budget_exceeded` | 402 | E klidinaskoro budžeto sas pherdo. Finalno: mang katar o klidinasko malavipen te vazdel les. |
| `conflict` | 409 | O resurso nane andro stanje savo mukhel kadava mangipen. |
| `rate_limited` | 429 | Ažukhar `Retry-After` sekunda, paša palem bičhav. |
| `upstream_error` | 502 | O modelosko backend našľilo. Šaj te bičhaves palem sa `Idempotency-Key`-esa: kerel pes palem; na lilăsarde tuke. |
| `service_unavailable` | 503 | E API si phandli vaj jekh zavisnost si tele. Bičhav palem maj palal. |
| `internal_error` | 500 | Amaro bilačhipen. Bičhav palem; te ačhol, kontaktir sarvosenge e vriama thaj `request_id`-sa. |

## Kodura

### `invalid_request`

Generično bilačho mangipen (400).

### `invalid_json`

O telo nane validno JSON (400).

### `invalid_body`

O telo si validno JSON, numa nane objektos; o modelosko inputo musaj te ovel JSON objektos (400).

### `body_too_large`

O telo si bareder katar 16 MB (413). Uploadin bare fajlo thaj bičhav lenko URL vareske (dik [Fajlo](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Jekh query parametro si lačho bilačhe vrednostesa, sar `limit` avri katar 1 dži 100, `wait` nane numero, jekh angluno
`status` vaj `category`, vaj `storage` si aver katar `permanent` / `temporary` (400). `param` sikavel les.

### `invalid_category`

`GET /openapi.json?category=` sikavel kategorija savi nane (400). `GET https://api.doitong.com/v1/categories` sikavel len.

### `invalid_cursor`

O `cursor` e listakere mangipnasko nane katar kadava list (400). Startin palem bizo cursor.

### `invalid_idempotency_key`

O `Idempotency-Key` header si šuto vaj lungereder katar 255 karakterura (400).

### `invalid_arguments`

Jekh MCP toolsko mangipen si bi argumentosa vaj bilačho argumentosa (numaj MCP). `param` sikavel o argumento.

### `invalid_input`

O modelosko inputo na džal validacija (422): angluno parametro (o message phenel o najpašeder validno nav),
pharuvlo potrebno parametro, bilačho tipo, vrednost avri katar e mukhle lista vaj range, vaj duj: o kanonicko thaj o
native nav dena pese aver vrednostenca. `param` si o angluno bilačho parametro thaj `details` sikavel savoren.
Nič na ovel lilăslo.

### `unsupported_file`

Jekh fajlo si tipesa savo amen na prihvatinas (422), sar upload sas unsupported extension-esa, vaj jekh `content_type`
savo na podhodil e extensionesa.

### `invalid_webhook_url`

`webhook_url` nane public `https://` URL (422). Privatno, lokalno thaj čisto `http://` adrese na prihvatinas.

### `missing_api_key`

O endpoint mangel API klidin thaj khonik na bičhalda les (401).

### `invalid_api_key`

E klidin nane prinžardi, sas revokime vaj pherdi e vriama (401).

### `insufficient_scope`

E klidin nane la scope savi mangel kadava mangipen (403), sar `models:run` vaš jekh run, vaj `models:read` te gindis
mangipnen thaj balanso. Dik [Authentication](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

O konto si phandlo vaj suspendime (403). Leskere klidin na keren maj buti.

### `not_found`

O drom nane (404).

### `model_not_found`

Nane jekh public modelo kadaja id-esa (404). Lister e modelura `GET https://api.doitong.com/v1/models`-sa.

### `request_not_found`

Nane mangipen kadala id-esa andro tiro konto (404). Aver kontonge mangipena nikana na dikhľon.

### `insufficient_credits`

E kontosko **API balanso** (API krediti, 1,000 API krediti = $1 — na o krediti e Doitong aplikacijenge) na pokrival
kadava mangipnasko mol (402). E response bičhalel pes angleder so vareso lilăslo. O greškipen ingerel `top_up_url`; thode love
pe [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) thaj bičhav palem.

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

O mangipen bi prela o APIske klidinesko korkorutno budžeto andro API krediti (402). O budžeto si thovdo e klidineskere malavesa; palem bičhavipen na pomožinel dži von na vazden les.

### `conflict`

O mangipen si andro konfliktos e akharestune stāvosa e resursosko (409).

### `idempotency_mismatch`

O `Idempotency-Key` sas već vakerdo avere telesa (409). Istinav nevo klidin vaš nevo keripen.

### `idempotency_in_progress`

Jekh mangipen saje `Idempotency-Key`-esa kerel pes akana (409). Bičhav palem palal jekh momentos te les.

### `request_active`

O mangipen si ajšukar `queued` vaj `running`, numa nane les fajlo te deletin akana (409). Deletin len kana agorisal.

### `not_cancelable`

O mangipen si već `succeeded` vaj `failed` thaj na šaj te cancelin les (409).

### `rate_limited`

E klidin kerda but mangipena andro akharutno vriamasko intervalos (429). Dik o `X-RateLimit-*` thaj `Retry-After` headerura.

### `too_many_inflight`

O konto si već le 10 mangipena `queued` vaj `running` (429). Startin aver kana jekh lendar agorisal.

### `upstream_error`

O modelosko backend na prihvatinda vaj našľarda o mangipen (502 pe run, vaj `failed` kadale kodosa pe mangipnasko objektos). E API krediti
iren pes. Te o backend korkorutno na prihvatinda o inputo, o mangipen anel `422 invalid_input` leskere messagesa.

### `upstream_lost`

O modelosko backend maj na džanel o mangipen, vaš oda nikana na avela rezultato. Agoril pes sar `failed` kadale kodosa
(tipo `upstream_error`) thaj iren pes. Ker les palem.

### `timeout`

O mangipen kerda buteder katar lesko limitos (15 minuta vaš kipo, 60 vaš video, 30 avera) thaj sas ačhavdo. Agoril pes sar
`failed` kadale kodosa thaj iren pes.

### `service_unavailable`

E API si tikno phandli, vaj jekh zavisnost sar uploadura e fajlonge si tele (503). Bičhav palem maj palal.

### `internal_error`

Vareso phagľilo amende (500). Bičhav palem; te ačhol, kontaktir sarvosen.

### `charge_failed`

O konto na šaj sas lilăslo vaš jekh interno problemos (500). O mangipen si značime `failed`; nič na sas lilăslo.
Bičhav palem.

### `pricing_unavailable`

O modelosko mol nane konfigurime, vaš oda akana na šaj te ovel phenlo vaj te kerel pes (500).