# Feeler

All Endpunkt feelen op déiselwecht Manéier: en HTTP-Status an een 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"
  }
}
```

| Feld | Bedeitung |
|---|---|
| `type` | Iwwergräifend Klass vum Feeler. Entscheet domat, wat ze maachen ass. |
| `code` | Exakte Grond, stabil a vu Maschinne liesbar. All Code huet eng Sektioun hei drënner; `doc_url` verlinkt dorop. |
| `message` | Fir Mënsche liesbar Erklärung, sécher fir ze loggen oder engem Entwéckler ze weisen. |
| `param` | Den Input-Parameter oder Header mam Feeler, wa sou een existéiert. |
| `details` | Bei Input-Feeler all fonnt Problem: `[{ "param", "message" }]`. |
| `request_id` | D'Ufro, op déi et sech bezitt, wa sou eng existéiert. |

Fir en Uruff, deen e Feeler zeréckgëtt, gëtt näischt verrechent. Eng Ufro, déi *nodeems* se ugeholl gouf feelerschléit, behält de Status
`failed`, huet `error: { "type", "code", "message" }` am Ufro-Objet a kritt automatesch e Remboursement.

## Zorten

| Zort | HTTP-Status | Wat ze maachen ass |
|---|---|---|
| `invalid_request` | 400, 413 oder 422 | D'Ufro korrigéieren. Dee selwechten Uruff nach eng Kéier ze schécken feelt erëm. |
| `authentication_error` | 401 | E gültege Schlëssel an `Authorization: Bearer <key>` schécken. |
| `permission_error` | 403 | E Schlëssel mat dem néidege Scope benotzen. |
| `not_found` | 404 | De Modell-ID oder d'Ufro-ID iwwerpréiwen. |
| `insufficient_credits` | 402 | Den API-Saldo oplueden (`top_up_url` am Feeler). |
| `budget_exceeded` | 402 | Den eegene Budget vum Schlëssel ass opgebraucht. Definitiv: de Besëtzer vum Schlëssel froen, en ze erhéijen. |
| `conflict` | 409 | D'Ressource ass net an engem Zoustand, deen dësen Uruff erlaabt. |
| `rate_limited` | 429 | `Retry-After` Sekonnen waarden an dann nach eng Kéier probéieren. |
| `upstream_error` | 502 | De Backend vum Modell ass feelergeschloen. Sécher mat deem selwechten `Idempotency-Key` nach eng Kéier probéieren: et leeft nach eng Kéier; et gouf näischt verrechent. |
| `service_unavailable` | 503 | D'API ass pauséiert oder eng Ofhängegkeet ass net disponibel. Méi spéit nach eng Kéier probéieren. |
| `internal_error` | 500 | Eise Feeler. Nach eng Kéier probéieren; wann et weider besteet, de Support mat der Zäit an `request_id` kontaktéieren. |

## Coden

### `invalid_request`

Generesch falsch geformt Ufro (400).

### `invalid_json`

De Kierper ass kee gültege JSON (400).

### `invalid_body`

De Kierper ass gültege JSON, awer keen Objet; de Modell-Input muss e JSON-Objet sinn (400).

### `body_too_large`

De Kierper ass méi grouss wéi 16 MB (413). Grouss Dateien eroplueden an amplaz hir URL weiderginn (kuckt [Dateien](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

E Query-Parameter huet e falsche Wäert, zum Beispill `limit` ausserhalb vun 1 bis 100, `wait` ass keng Zuel, en onbekannte
`status` oder `category`, oder `storage` ass net `permanent` / `temporary` (400). `param` nennt en.

### `invalid_category`

`GET /openapi.json?category=` nennt eng Kategorie, déi net existéiert (400). `GET https://api.doitong.ru/v1/categories` weist se op.

### `invalid_cursor`

De `cursor` vun engem Lëschten-Uruff gehéiert net zu dëser Lëscht (400). Ouni Cursor nei ufänken.

### `invalid_idempotency_key`

Den `Idempotency-Key`-Header ass eidel oder méi laang wéi 255 Zeechen (400).

### `invalid_arguments`

En MCP-Tool-Uruff huet en fehlenden oder falsch geformten Argument (nëmmen MCP). `param` nennt d'Argument.

### `invalid_input`

De Modell-Input passéiert d'Validéierung net (422): en onbekannte Parameter (d'Message proposéiert den noosten gültege Numm),
e feelende erfuerderleche Parameter, e falschen Typ, e Wäert ausserhalb vun der erlaabter Lëscht oder dem erlaabte Beräich, oder souwuel de kanoneschen an den
native Numm mat ënnerschiddleche Wäerter. `param` ass den éischte problematesche Parameter an `details` list all déi betraffen.
Et gëtt näischt verrechent.

### `unsupported_file`

Eng Datei huet en Typ, dee mir net akzeptéieren (422), zum Beispill en Upload mat enger net ënnerstëtzter Extensioun, oder e `content_type`,
deen net mat der Extensioun iwwerstëmmt.

### `invalid_webhook_url`

`webhook_url` ass keng ëffentlech `https://`-URL (422). Privat, lokal a reng `http://`-Adresse gi refuséiert.

### `missing_api_key`

Den Endpunkt brauch en API-Schlëssel, an et gouf keen geschéckt (401).

### `invalid_api_key`

De Schlëssel ass onbekannt, zréckgeruff oder ofgelaf (401).

### `insufficient_scope`

Dem Schlëssel feelt de Scope, deen dësen Uruff brauch (403), zum Beispill `models:run` fir e Run oder `models:read` fir
Ufroen an de Saldo ze liesen. Kuckt [Authentifikatioun](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

De Kont ass zougemaach oder suspendéiert (403). Seng Schlëssele funktionéieren net méi.

### `not_found`

De Wee existéiert net (404).

### `model_not_found`

Kee ëffentleche Modell huet dës ID (404). Modeller mat `GET https://api.doitong.ru/v1/models` oplëschten.

### `request_not_found`

Et gëtt keng Ufro mat dëser ID an Ärem Kont (404). Ufroen vun anere Konten sinn ni siichtbar.

### `insufficient_credits`

Den **API-Saldo** vum Kont (API-Kreditter, 1.000 API-Kreditter = 1 $ — net d'Kreditter vun den Doitong-Apps) deckt de Präis vun dësem Uruff net (402). D'Äntwert gëtt geschéckt, ier eppes verrechent gëtt. De Feeler enthält `top_up_url`; Suen op [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance) dobäisetzen an nach eng Kéier probéieren.

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

Den Uruff géif den eegene Budget vum API-Schlëssel an API-Kreditter iwwerschreiden (402). De Budget gëtt vum Besëtzer vum Schlëssel festgeluecht; nach eng Kéier probéieren hëlleft net, bis en en erhéicht.

### `conflict`

Den Uruff steet am Konflikt mam aktuelle Zoustand vun der Ressource (409).

### `idempotency_mismatch`

Den `Idempotency-Key` gouf scho mat engem anere Kierper benotzt (409). Fir eng nei Operatioun en neie Schlëssel benotzen.

### `idempotency_in_progress`

Eng Ufro mam selwechten `Idempotency-Key` gëtt grad erstallt (409). E Moment waarden an nach eng Kéier probéieren.

### `request_active`

D'Ufro ass nach `queued` oder `running`, dofir huet si nach keng Dateien, déi geläscht kënne ginn (409). Se läschen, nodeems si fäerdeg ass.

### `not_cancelable`

D'Ufro ass schonn `succeeded` oder `failed` a kann net ofgebrach ginn (409).

### `rate_limited`

De Schlëssel huet an der aktueller Fënster ze vill Uruffe gemaach (429). D'Header `X-RateLimit-*` an `Retry-After` kucken.

### `too_many_inflight`

De Kont huet schonn 10 Uroen `queued` oder `running` (429). Déi nächst ufänken, wann eng dovun fäerdeg ass.

### `upstream_error`

De Backend vum Modell huet d'Ufro refuséiert oder ass feelergeschloen (502 beim Run oder `failed` mat dësem Code op der Ufro). D'API-Kreditter ginn zréckbezuelt. Wann de Backend den Input selwer refuséiert huet, gëtt den Uruff mat `422 invalid_input` an där eegener Message zeréckginn.

### `upstream_lost`

De Backend vum Modell kennt d'Ufro net méi, dofir kënnt ni e Resultat. Si hält mat dësem Code op `failed` (Typ `upstream_error`) a kritt e Remboursement. Nach eng Kéier lafen.

### `timeout`

D'Ufro ass méi laang wéi hir Limit gelaf (15 Minutten fir Biller, 60 fir Video, soss 30) a gouf gestoppt. Si hält mat dësem Code op `failed` a kritt e Remboursement.

### `service_unavailable`

D'API ass temporär pauséiert oder eng Ofhängegkeet wéi Datei-Uploads ass net disponibel (503). Méi spéit nach eng Kéier probéieren.

### `internal_error`

Op eiser Säit ass eppes schifgaangen (500). Nach eng Kéier probéieren; wann et weider besteet, de Support kontaktéieren.

### `charge_failed`

De Kont konnt wéinst engem interne Problem net verrechent ginn (500). D'Ufro gëtt als `failed` markéiert; et gouf näischt ofgebucht. Nach eng Kéier probéieren.

### `pricing_unavailable`

De Präis vum Modell ass net konfiguréiert, dofir kann en elo net ugewisen oder ausgefouert ginn (500).