Chyby a stavové kódy
Naučte se číst chybové odpovědi API, řešit neúspěšné požadavky a rozlišovat chyby HTTP od selhání při překladu.
Než začnete dekódovat úspěšnou odpověď, zkontrolujte stavový kód HTTP. API na adrese https://api.lingo.dev/v2 hlásí chyby pomocí podrobností o problému ve formátu JSON. I úspěšně načtená úloha může obsahovat informace o neúspěšném zpracování, proto zkontrolujte také její stav.
Jak číst chybovou odpověď #
Chybové odpovědi používají Content-Type: application/problem+json. Mezi běžná pole patří type, title, status a detail. Pojmenované problémy obsahují také pole určující dotčený prostředek nebo způsob nápravy.
Tento příklad ukazuje chybějící lokalizační úlohu:
{
"type": "https://lingo.dev/docs/api/errors/localization-job-not-found",
"title": "Localization job not found",
"status": 404,
"detail": "Localization job lfr_example not found.",
"id": "lfr_example"
}URI v poli type identifikuje problém. Pole a koncové body jednotlivých pojmenovaných problémů najdete v katalogu chyb API. Při ukládání nebo klasifikaci chyby ponechte vrácené URI beze změny.
Oprava neplatného požadavku #
Požadavek, který neprojde validací, vrátí 400 Bad Request s type: "about:blank". Pokud jsou k dispozici podrobnosti o validaci, errors uvádí u každého problému path a message:
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Request validation failed",
"errors": [
{
"path": ["payload", "documents", 0, "source"],
"message": "Expected a JSON object"
}
]
}Cesta začíná částí požadavku, která se validuje, například payload. Za ní následují názvy vlastností a indexy polí počítané od nuly. Tento příklad označuje source v první položce documents v těle požadavku. Před opětovným odesláním opravte označenou hodnotu podle schématu koncového bodu. about:blank je obecný typ problému, a proto nemá záznam v katalogu pojmenovaných chyb.
Volba postupu nápravy #
| Stavový kód HTTP | Typická příčina | Další krok |
|---|---|---|
| 400 | Požadavek neodpovídá schématu trasy. | Podle vrácených podrobností o validaci opravte cestu, parametry dotazu, hlavičky nebo tělo požadavku. |
| 401 | Chybějící, neplatné nebo již neplatné přihlašovací údaje. | Načtěte správný klíč nebo obnovte uživatelskou relaci. |
| 402 | Nedostatek kreditů, funkce nedostupné v aktuálním plánu nebo neaktivní klíč služby po omezení oprávnění RBAC. | Zjistěte, jaká konkrétní podmínka chybu způsobila, a splňte příslušný požadavek na účet nebo plán. |
| 403 | Chybějící oprávnění, chybějící požadovaná identita uživatele nebo omezení dané příznakem funkce. | Zkontrolujte volajícího a požadavky na přístup k operaci. |
| 404 | Prostředek neexistuje nebo není pro tohoto volajícího viditelný. | Zkontrolujte identifikátor, organizaci a oprávnění k prostředku. |
| 409 | Operace je v rozporu se stavem prostředku. | Načtěte aktuální stav prostředku. Podle uvedených pokynů nahrajte chybějící artefakty, dokončete probíhající zpracování nebo obnovte uzavřenou kontrolu. |
| 413 | Nahrávaná data nebo tělo požadavku překračují limit velikosti. | Zmenšete vstup nebo rozdělte zpracování; každý nahrávaný artefakt může mít až 25 MiB. |
| 422 | Požadavek má platnou strukturu, ale porušuje omezení operace. | Odstraňte uvedený problém, například neplatnou úpravu při kontrole nebo opětovně použitý klíč idempotence. |
| 429 | Byl dosažen limit spotřeby nebo operací. | Pokud je v podrobnostech problému uvedeno, kdy požadavek zopakovat, tento čas dodržte. Jinak před opakováním zkontrolujte limit účtu. |
| 5xx | Server nebo závislá služba nedokázaly požadavek dokončit. | Uchovejte ID prostředku a požadavku; požadavek opakujte pouze tehdy, pokud to odpovídá sémantice operace. |
detail vysvětluje konkrétní selhání; samotný stavový kód k úplné klasifikaci nestačí. Odpovědi z proxy serveru nebo odpovědi při síťové chybě nemusí obsahovat tělo s popisem problému. Pro diagnostiku uchovejte jejich stavový kód HTTP a čitelný text odpovědi, ale nezapisujte do protokolů tajné údaje.
Opakované odeslání lokalizačního požadavku #
Před odesláním požadavku na vytvoření uložte jeho Idempotency-Key. Pokud se odpověď ztratí, zopakujte stejný požadavek se stejným klíčem a získáte původní úlohu. S novým klíčem se vytvoří nová úloha.
Po vytvoření uložte ID úlohy. Než se rozhodnete vytvořit další, načtěte stávající úlohu. Nahrávaná data musí přesně odpovídat bajtům určeným jejich adresou SHA-256; před spuštěním dokončete všechna chybějící nahrávání. Opakované volání /start pracuje se stejnou úlohou.
Podmínky pro přijetí se kontrolují při spuštění. V případě DailyTokenLimitReached nebo nedostatku kreditů zůstane úloha ve stavu čekání a po vyřešení problému s účtem ji bude možné spustit později. Opakované vytváření nových úloh omezení účtu nevyřeší.
Rozlišení selhání požadavku od selhání zpracování #
Stavový kód HTTP 200 z GET /v2/localization/jobs/:id znamená, že úloha byla načtena. Její status._tag ale může být i tak Failed. Zkontrolujte status.message, stav každého cíle a varování a selhání jednotlivých fází.
Dokončené cíle zůstávají dostupné ke stažení, i když jiný cíl selže. Uchovejte je a po odstranění příčiny odešlete pouze to, co je třeba znovu vygenerovat. Vypršení časového limitu dotazování na straně klienta úlohu nezruší.
Zřizování má vlastní výsledky podle typu a postupy nápravy. Rozhodnutí při kontrole mají vlastní chyby související s uzavřenou kontrolou a neplatnými úpravami. Při nápravě vycházejte ze stavu těchto prostředků. Ne každé selhání je důvodem k opakování původního zápisu.