# Hibák

Minden végpont ugyanúgy hibázik: egy HTTP-állapotkódot és egyetlen JSON-burkot ad vissza.

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

| Mező | Jelentés |
|---|---|
| `type` | A hiba általános osztálya. Ez alapján döntse el, mi a teendő. |
| `code` | A pontos, stabil és géppel olvasható ok. Minden kódhoz tartozik egy alábbi szakasz; a `doc_url` erre hivatkozik. |
| `message` | Ember számára olvasható magyarázat, amely biztonságosan naplózható vagy megjeleníthető egy fejlesztőnek. |
| `param` | A hibás bemeneti paraméter vagy fejléc, ha van ilyen. |
| `details` | Bemeneti hibáknál minden megtalált probléma: `[{ "param", "message" }]`. |
| `request_id` | Az érintett kérés azonosítója, ha létezik. |

A hibát visszaadó hívásért nem számítunk fel díjat. A kérés, amely az elfogadása *után* hibázik, `failed` állapotú marad, a kérésobjektumban az `error: { "type", "code", "message" }` értéket hordozza, és automatikusan visszatérítésre kerül.

## Típusok

| Típus | HTTP-állapot | Teendő |
|---|---|---|
| `invalid_request` | 400, 413 vagy 422 | Javítsa a kérést. Ugyanennek a hívásnak az újrapróbálása ismét hibázik. |
| `authentication_error` | 401 | Küldjön érvényes kulcsot az `Authorization: Bearer <key>` fejlécben. |
| `permission_error` | 403 | Használjon a szükséges hatókörrel rendelkező kulcsot. |
| `not_found` | 404 | Ellenőrizze a modell- vagy kérésazonosítót. |
| `insufficient_credits` | 402 | Töltse fel az API-egyenleget (`top_up_url` a hibában). |
| `budget_exceeded` | 402 | A kulcs saját kerete elfogyott. Végső megoldásként kérje meg a kulcs tulajdonosát a keret emelésére. |
| `conflict` | 409 | Az erőforrás nincs olyan állapotban, amely lehetővé teszi ezt a hívást. |
| `rate_limited` | 429 | Várjon `Retry-After` másodpercet, majd próbálja újra. |
| `upstream_error` | 502 | A modell háttérrendszere hibázott. Biztonságosan újrapróbálható ugyanazzal az `Idempotency-Key` értékkel: újra lefut, és nem számítottunk fel díjat. |
| `service_unavailable` | 503 | Az API szünetel, vagy egy függőség nem érhető el. Próbálja később. |
| `internal_error` | 500 | A mi hibánk. Próbálja újra; ha fennáll, forduljon az ügyfélszolgálathoz az időpont és a `request_id` megadásával. |

## Kódok

### `invalid_request`

Általánosan hibásan formázott kérés (400).

### `invalid_json`

A törzs nem érvényes JSON (400).

### `invalid_body`

A törzs érvényes JSON, de nem objektum; a modell bemenetének JSON-objektumnak kell lennie (400).

### `body_too_large`

A törzs nagyobb 16 MB-nál (413). Töltsön fel nagy fájlokat, és adja át helyettük az URL-jüket (lásd: [Fájlok](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Egy lekérdezési paraméter értéke hibás, például a `limit` értéke nincs 1 és 100 között, a `wait` nem szám, ismeretlen a `status` vagy a `category`, illetve a `storage` értéke nem `permanent` / `temporary` (400). A `param` nevezi meg.

### `invalid_category`

A `GET /openapi.json?category=` nem létező kategóriát nevez meg (400). A `GET https://api.doitong.com/v1/categories` felsorolja őket.

### `invalid_cursor`

A listázó hívás `cursor` értéke nem ehhez a listához tartozik (400). Kezdje újra kurzor nélkül.

### `invalid_idempotency_key`

Az `Idempotency-Key` fejléc üres vagy 255 karakternél hosszabb (400).

### `invalid_arguments`

Egy MCP-eszközhívásból hiányzik egy argumentum, vagy az hibásan formázott (csak MCP). A `param` nevezi meg az argumentumot.

### `invalid_input`

A modell bemenete nem felel meg az ellenőrzésnek (422): ismeretlen paraméter, hiányzó kötelező paraméter, hibás típus, az engedélyezett listán vagy tartományon kívüli érték, illetve a kanonikus és a natív név egyaránt meg van adva eltérő értékekkel. A `param` az első hibás paramétert nevezi meg, a `details` pedig mindet felsorolja. Ezért nem számítunk fel díjat.

### `unsupported_file`

A fájl típusa nem támogatott (422), például a feltöltés kiterjesztése nem támogatott, vagy a `content_type` nem egyezik a kiterjesztéssel.

### `invalid_webhook_url`

A `webhook_url` nem nyilvános `https://` URL (422). A privát, helyi és egyszerű `http://` címeket elutasítjuk.

### `missing_api_key`

A végpont API-kulcsot igényel, de nem küldtek kulcsot (401).

### `invalid_api_key`

A kulcs ismeretlen, visszavont vagy lejárt (401).

### `insufficient_scope`

A kulcsból hiányzik a híváshoz szükséges hatókör (403), például futtatáshoz a `models:run`, a kérések és az egyenleg olvasásához pedig a `models:read`. Lásd: [Hitelesítés](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

A fiók lezárt vagy felfüggesztett (403). A kulcsai többé nem működnek.

### `not_found`

Az útvonal nem létezik (404).

### `model_not_found`

Nincs ilyen azonosítójú nyilvános modell (404). A modelleket a `GET https://api.doitong.com/v1/models` paranccsal listázhatja.

### `request_not_found`

A fiókjában nem létezik ilyen azonosítójú kérés (404). Más fiókok kérései soha nem láthatók.

### `insufficient_credits`

A fiók **API-egyenlege** (API-kredit, 1000 API-jóváírás = 1 $ — nem a Doitong alkalmazások kreditjei) nem fedezi a hívás árát (402). A válasz még a terhelés előtt elküldésre kerül. A hiba tartalmazza a `top_up_url` értéket; töltsön fel pénzt itt: [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance), majd próbálja újra.

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

A hívás túllépné az API-kulcs saját, API-kreditben megadott keretét (402). A keretet a kulcs tulajdonosa állítja be; az újrapróbálás addig nem segít, amíg meg nem emeli.

### `conflict`

A hívás ütközik az erőforrás aktuális állapotával (409).

### `idempotency_mismatch`

Az `Idempotency-Key` értéket már más törzzsel használták (409). Új művelethez használjon új kulcsot.

### `idempotency_in_progress`

Éppen most hoznak létre egy kérést ugyanazzal az `Idempotency-Key` értékkel (409). Egy pillanat múlva próbálja újra a lekéréséhez.

### `request_active`

A kérés még `queued` vagy `running` állapotú, ezért egyelőre nincsenek törölhető fájljai (409). A törlést a befejezése után végezze el.

### `not_cancelable`

A kérés már `succeeded` vagy `failed` állapotú, ezért nem szakítható meg (409).

### `rate_limited`

A kulcs túl sok kérést küldött az aktuális időablakban (429). Lásd az `X-RateLimit-*` és `Retry-After` fejléceket.

### `too_many_inflight`

A fiókban már 10 `queued` vagy `running` kérés van (429). A következőt akkor indítsa el, amikor egyikük befejeződik.

### `upstream_error`

A modell háttérrendszere elutasította vagy nem tudta feldolgozni a kérést (futtatáskor 502, illetve a kérésen ezzel a kóddal `failed`). Az API-krediteket visszatérítjük. Ha maga a háttérrendszer utasította el a bemenetet, a hívás helyette `422 invalid_input` hibával és annak üzenetével tér vissza.

### `upstream_lost`

A modell háttérrendszere már nem ismeri a kérést, ezért eredmény soha nem érkezik. A kérés ezzel a kóddal és `upstream_error` típusban `failed` állapotú lesz, a díjat pedig visszatérítjük. Futtassa újra.

### `timeout`

A kérés túllépte a korlátját (képeknél 15 perc, videónál 60, egyébként 30), ezért leállítottuk. `failed` állapotú lesz ezzel a kóddal, és a díjat visszatérítjük.

### `service_unavailable`

Az API ideiglenesen szünetel, vagy egy függőség, például a fájlfeltöltés, nem érhető el (503). Próbálja később.

### `internal_error`

Valami meghibásodott a mi oldalunkon (500). Próbálja újra; ha fennáll, forduljon az ügyfélszolgálathoz.

### `charge_failed`

Belső hiba miatt nem sikerült megterhelni a fiókot (500). A kérés `failed` állapotú lesz; nem vontunk le semmit. Próbálja újra.

### `pricing_unavailable`

A modell ára nincs beállítva, ezért jelenleg nem kérhető rá árajánlat, és nem futtatható (500).