# Errurs

Mintga endpoint fallescha en la medema moda: in status HTTP ed ina enveloppa 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"
  }
}
```

| Champ | Senn |
|---|---|
| `type` | Classa generala da l'errur. Decida qua che far. |
| `code` | Raschun exacta, stadaivla e legibla per maschinas. Mintga code ha ina secziun sutvart; `doc_url` maina ad ella. |
| `message` | Explicaziun legibla per umans, segira per scriver en protocols u mussar ad in sviluppader. |
| `param` | Il parameter d'input u l'intestaziun ch'è responsabla, sch'igl è in tal. |
| `details` | Per errurs d'input, mintga problem chattà: `[{ "param", "message" }]`. |
| `request_id` | La dumonda pertutgada, sch'ina exista. |

Nagut na vegn addebità per ina clamada che returna in'errur. Ina dumonda che fallescha *suenter* ch'ella è vegnida acceptada mantegna il status
`failed`, porta `error: { "type", "code", "message" }` sin l'object da la dumonda ed vegn restituida automaticamain.

## Tipos

| Tip | Status HTTP | Cha far |
|---|---|---|
| `invalid_request` | 400, 413 u 422 | Curregia la dumonda. Repetir la medema clamada fallescha puspè. |
| `authentication_error` | 401 | Trametta ina clav valida en `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Utilisescha ina clav cun il scope necessari. |
| `not_found` | 404 | Controlla l'identificader dal model u da la dumonda. |
| `insufficient_credits` | 402 | Fa ina chargiada dal saldo API (`top_up_url` en l'errur). |
| `budget_exceeded` | 402 | Il budget da la clav è consumà. Final: dumonda al proprietari da la clav da l'auzar. |
| `conflict` | 409 | La resursa n'è betg en in stadi che permetta questa clamada. |
| `rate_limited` | 429 | Spetga `Retry-After` secundas e repeta lura. |
| `upstream_error` | 502 | Il backend dal model ha fallì. Ina repetiziun cun la medema `Idempotency-Key` è segira: ella vegn exequida puspè; nagut n'è vegnì addebità. |
| `service_unavailable` | 503 | L'API è pausada u ina dependenza n'è betg disponibla. Repeta pli tard. |
| `internal_error` | 500 | Nossa errur. Repeta; sch'ella persista, contactescha il support cun il temp e `request_id`. |

## Codes

### `invalid_request`

Dumonda generica malfurmada (400).

### `invalid_json`

Il corp n'è betg JSON valid (400).

### `invalid_body`

Il corp è JSON valid, ma betg in object; l'input dal model sto esser in object JSON (400).

### `body_too_large`

Il corp è pli grond che 16 MB (413). Chargia datotecas grondas e passa lur URL empè da quai (vesa [Datotecas](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

In parameter da query ha ina valur faussa, per exempel `limit` ordaifer 1 fin 100, `wait` betg numer, in `status` u `category` nunenconuschent, u `storage` auter che `permanent` / `temporary` (400). `param` inditgescha el.

### `invalid_category`

`GET /openapi.json?category=` inditgescha ina categoria inexistenta (400). `GET https://api.doitong.ru/v1/categories` las enumerescha.

### `invalid_cursor`

Il `cursor` d'ina clamada da glista na tutga betg a questa glista (400). Cumenza puspè senza cursor.

### `invalid_idempotency_key`

L'intestaziun `Idempotency-Key` è vida u pli lunga che 255 caracteras (400).

### `invalid_arguments`

Ina clamada d'in utensil MCP ha in argument mancà u malfurmà (MCP mo). `param` inditgescha l'argument.

### `invalid_input`

L'input dal model na passa betg la validaziun (422): in parameter nunenconuschent (il messadi propona il num valid il pli datiers), in parameter obligatoric mancà, in tip fauss, ina valur ordaifer la glista u l'interval permess, u tant il num canonic sco il num nativ cun differentas valurs. `param` è il prim parameter problematic e `details` enumerescha tuts. Nagut na vegn addebità.

### `unsupported_file`

Ina datoteca ha in tip che nus na acceptain betg (422), per exempel ina chargiada cun in'estensiun betg sustegnida, u in `content_type` che na correspunda betg a l'estensiun.

### `invalid_webhook_url`

`webhook_url` n'è betg ina URL publica `https://` (422). Adressas privatas, localas e simplas `http://` vegnan refusadas.

### `missing_api_key`

L'endpoint dovra ina clav API e nagina n'è vegnida tramessa (401).

### `invalid_api_key`

La clav n'è betg enconuschenta, è vegnida revocada u è scadida (401).

### `insufficient_scope`

La clav na posseda betg il scope necessari per questa clamada (403), per exempel `models:run` per in'execuziun, u `models:read` per leger dumondas e saldo. Vesa [Autentificaziun](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Il conto è serrà u suspendì (403). Sias clavs na funcziunan pli betg.

### `not_found`

La via n'exista betg (404).

### `model_not_found`

Nagin model public n'ha quest identificader (404). Enumerescha ils models cun `GET https://api.doitong.ru/v1/models`.

### `request_not_found`

Nagina dumonda cun quest identificader n'exista en tes conto (404). Dumondas d'auters contos na vegnan mai mussadas.

### `insufficient_credits`

Il **saldo API** dal conto (credits API, 1 000 credits API = $1 — betg ils credits da las apps Doitong) na cuvra betg il pretsch da questa clamada (402). La resposta vegn tramessa avant che insumma insatge vegn addebità. L'errur porta `top_up_url`; agiunta daners tar [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance) e repeta.

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

La clamada surpassass il budget da la clav API en credits API (402). Il budget vegn fixà dal proprietari da la clav; repeter gida betg fin ch'el n'è betg vegnì auzà.

### `conflict`

La clamada è en conflict cun il stadi actual da la resursa (409).

### `idempotency_mismatch`

L'`Idempotency-Key` è gia vegnida utilisada cun in auter corp (409). Utilisescha ina nova clav per ina nova operaziun.

### `idempotency_in_progress`

Ina dumonda cun la medema `Idempotency-Key` vegn creada gist ussa (409). Repeta en in mument per survegnir ella.

### `request_active`

La dumonda è anc `queued` u `running`, perquai ch'ella n'ha anc naginas datotecas da stizzar (409). Stizza ellas cura ch'ella è terminada.

### `not_cancelable`

La dumonda è gia `succeeded` u `failed` e na po betg pli vegnir annullada (409).

### `rate_limited`

La clav ha fatg memia bleras dumondas durant la fnestra actuala (429). Vesa las intestaziuns `X-RateLimit-*` e `Retry-After`.

### `too_many_inflight`

Il conto ha gia 10 dumondas `queued` u `running` (429). Cumenza la proxima cura che ina dad ellas è terminada.

### `upstream_error`

Il backend dal model ha refusà u fallì la dumonda (502 durant l'execuziun, u `failed` cun quest code sin la dumonda). Ils credits API vegnan restitutids. Sche il backend ha refusà l'input sez, returna la clamada `422 invalid_input` cun ses messadi.

### `upstream_lost`

Il backend dal model na sa betg pli da la dumonda, uschia che nagin resultat na vegn ad arrivar. Ella finescha sco `failed` cun quest code (tip `upstream_error`) ed vegn restituida. Exequescha ella puspè.

### `timeout`

La dumonda è currida pli ditg che sia limita (15 minutas per maletgs, 60 per video, 30 auter) ed è vegnida fermada. Ella finescha sco `failed` cun quest code ed è restituida.

### `service_unavailable`

L'API è temporarmain pausada, u ina dependenza sco chargiadas da datotecas n'è betg disponibla (503). Repeta pli tard.

### `internal_error`

Insatge è rut da nossa vart (500). Repeta; sch'ella persista, contactescha il support.

### `charge_failed`

Il conto na pudeva betg vegnir addebità pervi d'in problem intern (500). La dumonda vegn marcada `failed`; nagut n'è vegnì prendì. Repeta.

### `pricing_unavailable`

Il pretsch dal model n'è betg configurà, perquai ch'el na po betg vegnir calculà u exequì ussa (500).