Chyby a stavové kódy

Volání funguje ve vývoji. Teď ale píšete část, která poběží v produkci – catch blok. HTTP chyba z API třetí strany je sama o sobě neprůhledná: červený stavový kód a žádná jasná odpověď na jedinou otázku, na které ve tři ráno záleží – je problém v mém požadavku, mém klíči, mém tarifu, nebo na jejich serverech? A co z toho mám zkusit znovu a co mám ukázat uživateli?

Lingo.dev na to odpovídá strukturou. Každá chyba – z každého endpointu, synchronního i asynchronního – se vrací jako stejný JSON objekt se stavovým kódem z jedné pevně dané tabulky. Stavový kód není štítek, ale instrukce: řekne vám, jestli máte opravit požadavek, obměnit klíč, dobít účet, zpomalit, nebo požadavek zopakovat. Přečtěte kód a hned víte, co dál. Jeden error handler postavený na stavovém kódu pokryje celé API.

Na této stránce

• Formát chyby
• Stavové kódy
• Které chyby opakovat
• 402 vs 429: dva různé limity
• Kde najdete chyby asynchronních úloh

Formát chyby#

Každá odpověď mimo 2xx má stejné tělo: JSON objekt s jediným polem message, které popisuje, co se pokazilo.

{
  "message": "Invalid API key"
}

To je celý kontrakt. Není tu žádná obálka k rozbalení ani endpoint-specific formát chyb, který by vyžadoval zvláštní zacházení. Odpověď 400 z /process/localize a odpověď 404 při hledání úlohy vrací stejný formát – liší se jen stavový kód a text v message.

Stavové kódy#

Každou odpověď pokrývá sedm stavových kódů. Tady jsou seskupené podle toho, kdo je řeší – protože právě tohle seskupení zároveň určuje vaši strategii opakování.

Poslali jste něco, co požadavek nemůže splnit (opravte požadavek, neopakujte ho naslepo):

Vaše organizace narazila na limit účtu (řešení je v billing):

Něco selhalo na naší straně (přechodné – zkuste znovu):

401 a 403 vypadají podobně, ale neznamenají totéž: 401 znamená, že jsme volajícího vůbec nedokázali identifikovat, zatímco 403 znamená, že jsme klíč identifikovali, ale nemá povolený přístup. Řešením pro 401 je samotný klíč (obměňte ho nebo ho zkontrolujte); řešením pro 403 jsou oprávnění klíče.

Které chyby opakovat#

První otázka skeptického integrátora nad jakoukoli tabulkou chyb bývá ta, na kterou obvykle nedostane odpověď: které z nich mám opakovat? Odpověď dává seskupení výše.

• 4xx – neopakujte naslepo. 400, 401, 403 nebo 404 popisuje problém ve vašem požadavku. Opakování stejného požadavku povede ke stejné chybě. Opravte vstup, klíč nebo ID prostředku a pak ho odešlete znovu.
• 402 a 429 – zpomalte a pak vyřešte limit. Na úrovni požadavku nejde o přechodné chyby; další požadavek narazí na stejnou překážku, dokud se neposune samotný limit. Přestaňte opakovat v těsné smyčce, ukažte limit a vyřešte ho (dobitím kreditu nebo přechodem na vyšší tarif).
• 500 – opakujte s backoffem. Tohle je jediná skutečně přechodná třída. 500 může znamenat, že u daného volání timeoutovaly všechny nakonfigurované modely; opakování může skončit na zdravém modelu. Použijte exponenciální backoff a horní limit počtu pokusů.

402 vs 429: dva různé limity#

Tyto dva kódy na úrovni účtu znějí podobně – oba působí jako „něco vám došlo“ – a jejich záměna pošle vývojáře ke špatnému řešení. Jde o odlišné limity s odlišným řešením:

• 402 Payment Required – organizace narazila na svůj kreditní limit. To je billing hranice. Další volání budou dál selhávat, dokud se nezmění billing stav vaší organizace.
• 429 Too Many Requests – organizace narazila na svou denní kvótu tokenů. To je limit spotřeby, který se resetuje, a zvýšíte ho přechodem na vyšší tarif.

Proč je v handleru držet odděleně: 402 vyžaduje billing akci, kterou udělá člověk; 429 je kvóta, kterou buď vyčkáte, nebo navýšíte přechodem na vyšší tarif. Pokud obě schováte pod obecnou zprávu typu „problém s platbou“, skryjete tím, jakou páku má operátor skutečně použít.

Tělo odpovědi 402 vypadá stejně jako u každé jiné chyby – teprve stavový kód vám řekne, že jde o kreditní limit:

{
  "message": "Organization has reached its credit limit"
}

Kde najdete chyby asynchronních úloh#

Tady má smysl udělat jasnou čáru, protože právě tady přestává být handler stavových kódů tím správným nástrojem.

Stavové kódy na této stránce jsou na transportní úrovni: popisují, zda API přijalo a dokázalo obsloužit váš HTTP požadavek. 202 z asynchronního API znamená, že váš požadavek byl přijatý – ne že překlad uspěl. Asynchronní úloha může být bez problémů přijatá a přesto selhat později, když uprostřed běhu timeoutuje model. Takové selhání není HTTP stavový kód u vašeho původního volání; zachycuje se přímo na úloze.

Asynchronní selhání se tedy objevují na třech místech – a ani jedno z nich není v této tabulce:

• Stav jednotlivé úlohy. Neúspěšný jazyk nese na úloze status: "failed" a errorMessage. Viz stavy úloh.
• Stav skupiny. Když některé jazyky uspějí a jiné selžou, skupina hlásí partial – úspěšné jazyky se přesto doručí. Viz sledování skupiny úloh.
• Doručení webhookem. Selhání se doručí jako událost translation.failed s polem error. Viz doručení webhooků.

Je tu ještě jeden rozdíl, na kterém se lidé často zaseknou: když selže nekritická fáze v pipeline, úloha kvůli tomu neselže. Dokončí se se stavem completed_with_warnings a s upozorněními pro jednotlivé kroky místo chyby. To je otázka observability pipeline, ne chybového kódu – viz sledování běhů pipeline.

Další kroky#

Čistý error handler začíná u dvou oblastí, se kterými se při integraci setkáte jako první – autentizace a míst, kde asynchronní zpracování hlásí svůj vlastní výsledek.