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:

json
{
  "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:

json
{
  "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 HTTPTypická příčinaDalší krok
400Požadavek neodpovídá schématu trasy.Podle vrácených podrobností o validaci opravte cestu, parametry dotazu, hlavičky nebo tělo požadavku.
401Chybějící, neplatné nebo již neplatné přihlašovací údaje.Načtěte správný klíč nebo obnovte uživatelskou relaci.
402Nedostatek 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.
403Chybě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.
404Prostředek neexistuje nebo není pro tohoto volajícího viditelný.Zkontrolujte identifikátor, organizaci a oprávnění k prostředku.
409Operace 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.
413Nahrá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.
422Pož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.
429Byl 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.
5xxServer 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.