# Chyby

Každý endpoint selže stejným způsobem: HTTP stav a jeden obal 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"
  }
}
```

| Pole | Význam |
|---|---|
| `type` | Obecná třída chyby. Podle ní rozhodněte, co dělat. |
| `code` | Přesný důvod, stabilní a čitelný pro stroje. Každý kód má níže vlastní sekci; `doc_url` na ni odkazuje. |
| `message` | Vysvětlení čitelné pro člověka, bezpečné pro uložení do logu nebo zobrazení vývojáři. |
| `param` | Chybný vstupní parametr nebo hlavička, pokud existuje. |
| `details` | U vstupních chyb všechny nalezené problémy: `[{ "param", "message" }]`. |
| `request_id` | Požadavek, kterého se chyba týká, pokud existuje. |

Za volání, které vrátí chybu, se nic neúčtuje. Požadavek, který selže *poté*, co byl přijat, zůstane ve stavu
`failed`, v objektu požadavku obsahuje `error: { "type", "code", "message" }` a automaticky se refunduje.

## Typy

| Typ | HTTP stav | Co dělat |
|---|---|---|
| `invalid_request` | 400, 413 nebo 422 | Opravte požadavek. Opakování stejného volání znovu selže. |
| `authentication_error` | 401 | Pošlete platný klíč v `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Použijte klíč s požadovaným rozsahem oprávnění. |
| `not_found` | 404 | Zkontrolujte id modelu nebo požadavku. |
| `insufficient_credits` | 402 | Dobijte zůstatek API (`top_up_url` v chybě). |
| `budget_exceeded` | 402 | Vlastní rozpočet klíče je vyčerpán. Konečné řešení: požádejte vlastníka klíče o jeho navýšení. |
| `conflict` | 409 | Zdroj není ve stavu, který toto volání umožňuje. |
| `rate_limited` | 429 | Počkejte `Retry-After` sekund a poté požadavek zopakujte. |
| `upstream_error` | 502 | Backend modelu selhal. Opakování se stejným `Idempotency-Key` je bezpečné: požadavek se spustí znovu a nic vám nebylo účtováno. |
| `service_unavailable` | 503 | API je pozastavené nebo je nedostupná závislá služba. Zkuste to později. |
| `internal_error` | 500 | Chyba na naší straně. Zkuste to znovu; pokud přetrvává, kontaktujte podporu s časem a `request_id`. |

## Kódy

### `invalid_request`

Obecně nesprávně vytvořený požadavek (400).

### `invalid_json`

Tělo není platný JSON (400).

### `invalid_body`

Tělo je platný JSON, ale není objektem; vstup modelu musí být objekt JSON (400).

### `body_too_large`

Tělo je větší než 16 MB (413). Nahrajte velké soubory a místo nich předejte jejich URL (viz [Soubory](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Parametr dotazu má nesprávnou hodnotu, například `limit` mimo rozsah 1 až 100, `wait` není číslo, neznámý
`status` nebo `category`, případně `storage` jiný než `permanent` / `temporary` (400). `param` uvádí jeho název.

### `invalid_category`

`GET /openapi.json?category=` uvádí kategorii, která neexistuje (400). `GET https://api.doitong.ru/v1/categories` je vypisuje.

### `invalid_cursor`

`cursor` volání seznamu nepatří do tohoto seznamu (400). Začněte znovu bez kurzoru.

### `invalid_idempotency_key`

Hlavička `Idempotency-Key` je prázdná nebo delší než 255 znaků (400).

### `invalid_arguments`

Volání nástroje MCP má chybějící nebo nesprávně vytvořený argument (pouze MCP). `param` uvádí název argumentu.

### `invalid_input`

Vstup modelu neprojde validací (422): neznámý parametr (zpráva navrhne nejbližší platný název), chybějící povinný parametr,
nesprávný typ, hodnota mimo povolený seznam nebo rozsah, případně současně zadaný kanonický i nativní název s různými hodnotami. `param` je první chybný parametr a `details` uvádí všechny. Nic se neúčtuje.

### `unsupported_file`

Soubor má typ, který nepřijímáme (422), například nahraný soubor s nepodporovanou příponou nebo `content_type`,
který neodpovídá příponě.

### `invalid_webhook_url`

`webhook_url` není veřejná URL adresa `https://` (422). Soukromé, lokální a běžné adresy `http://` se odmítají.

### `missing_api_key`

Endpoint vyžaduje API klíč, ale žádný nebyl odeslán (401).

### `invalid_api_key`

Klíč je neznámý, odvolaný nebo prošlý (401).

### `insufficient_scope`

Klíči chybí rozsah oprávnění potřebný pro toto volání (403), například `models:run` pro spuštění nebo `models:read` pro čtení
požadavků a zůstatku. Viz [Autentizace](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Účet je uzavřený nebo pozastavený (403). Jeho klíče již nefungují.

### `not_found`

Cesta neexistuje (404).

### `model_not_found`

Žádný veřejný model nemá toto id (404). Modely vypíšete pomocí `GET https://api.doitong.ru/v1/models`.

### `request_not_found`

Ve vašem účtu neexistuje požadavek s tímto id (404). Požadavky jiných účtů nejsou nikdy viditelné.

### `insufficient_credits`

**Zůstatek API** účtu (API kredity, 1 000 kreditů API = 1 $ — nikoli kredity aplikací Doitong) nepokrývá cenu tohoto volání (402). Odpověď se odešle dříve, než se cokoli naúčtuje. Chyba obsahuje `top_up_url`; přidejte peníze na [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance) a požadavek zopakujte.

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

Volání by překročilo vlastní rozpočet API klíče v API kreditech (402). Rozpočet nastavuje vlastník klíče; opakování nepomůže, dokud ho nezvýší.

### `conflict`

Volání je v konfliktu s aktuálním stavem zdroje (409).

### `idempotency_mismatch`

`Idempotency-Key` již byl použit s jiným tělem (409). Pro novou operaci použijte nový klíč.

### `idempotency_in_progress`

Právě se vytváří požadavek se stejným `Idempotency-Key` (409). Za chvíli požadavek zopakujte a získejte ho.

### `request_active`

Požadavek je stále `queued` nebo `running`, takže zatím nemá žádné soubory ke smazání (409). Smažte je, až bude dokončen.

### `not_cancelable`

Požadavek již skončil stavem `succeeded` nebo `failed` a nelze ho zrušit (409).

### `rate_limited`

Klíč v aktuálním okně vytvořil příliš mnoho požadavků (429). Viz hlavičky `X-RateLimit-*` a `Retry-After`.

### `too_many_inflight`

Účet již má 10 požadavků ve stavu `queued` nebo `running` (429). Další spusťte, až jeden z nich skončí.

### `upstream_error`

Backend modelu požadavek odmítl nebo při jeho zpracování selhal (502 při spuštění nebo `failed` s tímto kódem na požadavku). API kredity se refundují. Pokud backend odmítl samotný vstup, volání místo toho vrátí `422 invalid_input` s příslušnou zprávou.

### `upstream_lost`

Backend modelu již požadavek nezná, takže výsledek nikdy nedorazí. Skončí stavem `failed` s tímto kódem (typ `upstream_error`) a refunduje se. Spusťte ho znovu.

### `timeout`

Požadavek běžel déle, než je jeho limit (15 minut pro obrázky, 60 pro video, jinak 30), a byl zastaven. Skončí stavem `failed` s tímto kódem a refunduje se.

### `service_unavailable`

API je dočasně pozastavené nebo je nedostupná závislá služba, například nahrávání souborů (503). Zkuste to později.

### `internal_error`

Na naší straně došlo k chybě (500). Zkuste to znovu; pokud přetrvává, kontaktujte podporu.

### `charge_failed`

Účet nelze zatížit kvůli internímu problému (500). Požadavek je označen jako `failed`; nic nebylo odečteno. Zkuste to znovu.

### `pricing_unavailable`

Cena modelu není nakonfigurována, takže ji nyní nelze zobrazit ani model spustit (500).