Průvodce API

Chyby

Zobrazit jako Markdown Aktualizováno 2026-10-22

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).

`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.com/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.

`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.com/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.com/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.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`

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).

Typy#

Kódy#

invalid_request#

invalid_json#

invalid_body#

body_too_large#

invalid_parameter#

invalid_category#

invalid_cursor#

invalid_idempotency_key#

invalid_arguments#

invalid_input#

unsupported_file#

invalid_webhook_url#

missing_api_key#

invalid_api_key#

insufficient_scope#

account_disabled#

not_found#

model_not_found#

request_not_found#

insufficient_credits#

budget_exceeded#

conflict#

idempotency_mismatch#

idempotency_in_progress#

request_active#

not_cancelable#

rate_limited#

too_many_inflight#

upstream_error#

upstream_lost#

timeout#

service_unavailable#

internal_error#

charge_failed#

pricing_unavailable#