Reference chybových kódů

Každá cesta selhání v platformě BizKitHub je pojmenovaná chyba, nikoli volně formulovaná zpráva. Když volání API selže z zdokumentovaného důvodu, odpověď nese stabilní, unikátní kód, který lze vyhledat v registru chyb a použít k porovnání vzorů klientskými integracemi. Toto je doplněk k článku API pro vývojáře: vysvětluje, jak interpretovat chyby vrácené těmito koncovými body.

Architektonický princip je jednoduchý: negativní výsledky si zaslouží stejnou péči jako ty pozitivní. Pokud požadavek musí selhat – chybí API klíč, slug produktu neexistuje, platební brána odmítla kartu – musí selhat zdokumentovaným, předvídatelným způsobem. Náhodné řetězce a nerozlišené kódy 500 jsou podle filozofie platformy chybami.

Anatomie chyby

Každá zdokumentovaná chyba má tři pevné atributy:

• Interní kód — unikátní identifikátor, například PUBLIC_API_KEY_DOES_NOT_EXIST. Toto je stabilní strojově čitelný identifikátor, na který by se měl váš klient přepínat. Je zaručeno, že nebude znovu použit pro jiný význam.
• HTTP status — stavový kód na úrovni transportu vrácený s tělem odpovědi. Výchozí hodnota je 500, pokud ji specifický typ chyby nepřepíše.
• Zpráva — krátký, lidsky čitelný popis toho, co se pokazilo. Určeno pro vývojáře, nikoli pro zákazníky; měli byste ji přeložit nebo nahradit uživatelsky přívětivým řetězcem ve vašem uživatelském rozhraní.

Registr je autoritativní. Pokud váš klient narazí na kód, který není v registru, jedná se o chybu platformy – nahlaste ji prosím prostřednictvím kanálu podpory.

Příklad

Když je volání API provedeno bez parametru apiKey – nebo se klíč nepřeloží na aktivní registraci – platforma vrátí chybu PUBLIC_API_KEY_DOES_NOT_EXIST. Toto není „chyba“ v abstraktním smyslu, je to tato konkrétní chyba: jedinečně pojmenovaná, zdokumentovaná na stabilní URL adrese a konzistentní napříč každým koncovým bodem, který ověřuje požadavky. Váš klient ji může jednou zachytit a nasměrovat každého volajícího přes stejnou cestu „prosím zkontrolujte svůj API klíč“.

Kde najít úplný seznam

Kompletní katalog chyb je generován automaticky z interního registru platformy a publikován na webu pro vývojářskou dokumentaci. Každý kód má svůj vlastní permalink, takže si můžete uložit do záložek nebo odkazovat na konkrétní chybu z vašich vlastních provozních příruček, zpráv o incidentech nebo uživatelských chybových zpráv:

https://docs.bizkithub.com/errors/<CODE>

Například https://docs.bizkithub.com/errors/PUBLIC_API_KEY_DOES_NOT_EXIST dokumentuje případ chybějícího API klíče samostatně. URL je stabilní – můžete na ni odkazovat z chybových zpráv na straně klienta a bude stále fungovat i roky poté, i když se interní implementace kontroly platformy změní.

Doporučené zpracování klientem

• Přepínejte podle interního kódu, nikoli podle zprávy. Zprávy mohou být přeformulovány pro jasnost; kódy nikdy nemění význam.
• V případě, že klient kód nerozpozná, vraťte se k HTTP statusu. Kódy 401/403/404/422/500 jsou smysluplné i bez dalšího parsování.
• Zalogujte interní kód a identifikátor požadavku (pokud je vrácen), aby podpora mohla přesně sledovat volání v protokolech platformy.
• Nezobrazujte syrové zprávy platformy koncovým uživatelům. Zprávy jsou orientovány na vývojáře; před zobrazením zákazníkovi nebo operátorovi je zabalte do vlastního textu.

Související články

• API — konvence požadavků/odpovědí REST API platformy.
• API klíč — nejčastější zdroj chybových kódů souvisejících s autentizací.
• Omezení rychlosti — chyby související s kvótami na klíč.