Kódy chyb GraphQL API

Chyba, kterou GraphQL API vrací, může nést stabilní strojový kód (code) a z něj odvozenou kategorii (category). Kód dosavadní text chyby doplňuje, nenahrazuje: pole errors i texty chyb na nejvyšší úrovni odpovědi zůstávají beze změny. Kód přichází na dvou místech (sloupec Kanál):

errorDetails — volitelné pole vedle errors ve výsledku mutace nebo dotazu. Položka i popisuje errors[i]: code, category, message (přesně errors[i]), text, field, params { name value }.
nejvyšší errors — klíč extensions u chyby v poli errors na nejvyšší úrovni odpovědi: code, category a podle potřeby field, params a text.

Server kódy doplňuje postupně. Chyba, u které kód chybí nebo je UNCLASSIFIED, se zpracuje podle textu jako dosud.

Dostupnost. Pole errorDetails vybírejte, jen když server ohlásí schopnost error-details (hlavička X-Depoto-Capabilities, viz Chyby GraphQL API). Klíč extensions server posílá na požádání, viz Chyby na nejvyšší úrovni.

Pravidla stability

Kód se nikdy nepřejmenuje, neodstraní, nepoužije pro jiný význam ani nezmění kategorii.
U konkrétní chyby se kód může změnit jedině z UNCLASSIFIED na konkrétní kód, vždy s ohlášením v novinkách. Kód, který server pro danou situaci jednou vrací, už se nemění: podrobnosti přibývají jako nové parametry, nová situace dostane nový kód.
Kód, který klient nezná, zpracujte podle jeho kategorie. Nové kódy průběžně přibývají.
Názvy parametrů jsou camelCase z písmen a číslic. Hodnoty jsou vždy řetězce, i čísla a true/false.
message a text jsou texty pro člověka, ne smluvní klíč. text je message bez dosavadních ozdob (předpona pole: , příčina v závorce), u některých kódů srozumitelnější věta (např. NOT_DELETABLE); zpřesnit se smí jen spolu s přechodem chyby z UNCLASSIFIED na konkrétní kód.
BAD_REQUEST a RATE_LIMITED jsou vyhrazené: vrací je jen vstupní kontrola požadavku (HTTP 400, HTTP 429) v dosavadním poli code chyby, formát těchto odpovědí se nemění.
Parametry v extensions mohou chybět i u kódu, který parametry uvádí — když jedna chyba zastupuje několik stejných selhání s různými podrobnostmi (např. dvě aliasované mutace v jednom dokumentu). Chybějící parametry neznamenají „bez podrobností“: načtěte stav znovu nebo použijte errorDetails.
Dokud server u některé chyby konkrétní kód nevrací, ponechte pro ni zpracování podle textu.

Parametry v tabulce jsou ty, které kód může nést; kterýkoli z nich může u konkrétní chyby chybět.

Kategorie

Kategorie	Význam
`request`	Chybný GraphQL dokument nebo tvar argumentů. Opravte dotaz.
`auth`	Volajícímu chybí oprávnění, nebo záznam patří mimo jeho firmu či pokladnu.
`not_found`	Záznam neexistuje nebo byl smazán.
`validation`	Neplatná vstupní hodnota. Opravte vstup; `field` ukazuje, kterou hodnotu.
`business`	Operaci nedovoluje pravidlo v aktuálním stavu dat.
`conflict`	Střet s existujícími daty.
`retry`	Odmítnuto dřív, než se cokoli zapsalo. Požadavek lze poslat znovu beze změny (u parametru `retryAfter` nebo hlavičky Retry-After až po uvedené době).
`outcome_unknown`	Selhalo tak, že zápis mohl proběhnout. Před opakováním načtěte stav, jinak hrozí zdvojený doklad.
`external`	Odmítl dopravce nebo jiná třetí strana.
`internal`	Chyba serveru.
`unknown`	Chyba zatím bez kódu (`UNCLASSIFIED`). Zpracujte ji podle textu.

Kódy

Kód	Kategorie	Význam	Parametry	Kanál
`NOT_FOUND`	`not_found`	Požadovaná entita neexistuje nebo byla smazána.	—	`errorDetails`, nejvyšší `errors`
`FORBIDDEN`	`auth`	Entita nebo záznam, na který vstup odkazuje, patří mimo firmu či pokladnu, ke které má volající přístup (zapisovat lze jen do vlastní firmy a jejích podřízených firem). U odkazu uvádí `field`, je-li známa, cestu k němu (např. `items[0].product`).	—	`errorDetails`, nejvyšší `errors`
`NOT_DELETABLE`	`business`	Entitu nelze smazat, protože na ni odkazují jiné záznamy nebo je chráněná proti smazání. `message` je stejný jako u `FORBIDDEN` (`Error 403: Forbidden.`), `text` je srozumitelná věta s důvodem, obvykle „Záznam nelze smazat, protože se stále používá.“; u příjmu nebo přeskladnění, jehož smazání by odebralo víc kusů, než je na skladě, „Pohyb nelze smazat: jeho smazání by odebralo víc kusů, než je na skladě (zboží už bylo vyskladněno nebo přeskladněno).“.	—	`errorDetails`
`ACCESS_DENIED`	`auth`	Volajícímu chybí role potřebná pro tuto operaci.	—	nejvyšší `errors`
`ORDER_BILL_NOT_PERMITTED`	`auth`	Volající nemá oprávnění vyskladnit objednávku a vystavit doklad.	—	`errorDetails`
`VALUE_REQUIRED`	`validation`	Povinná hodnota chybí nebo je prázdná.	—	`errorDetails`
`VALUE_NOT_UNIQUE`	`validation`	Hodnota už je použitá u jiného záznamu (např. EAN produktu nebo e-mail uživatele).	`value`	`errorDetails`
`VALUE_TOO_LONG`	`validation`	Hodnota je delší, než je povoleno.	`value`, `limit`	`errorDetails`
`VALUE_TOO_SHORT`	`validation`	Hodnota je kratší, než je povoleno.	`value`, `limit`	`errorDetails`
`VALUE_INVALID_CHOICE`	`validation`	Hodnota není jednou z povolených možností.	`value`	`errorDetails`
`VALUE_OUT_OF_RANGE`	`validation`	Hodnota je mimo povolený rozsah.	`value`, `limit`, `min`, `max`, `comparedValue`	`errorDetails`
`VALUE_INVALID_FORMAT`	`validation`	Hodnota nemá požadovaný formát (např. e-mail, URL nebo soubor inventury, který není platný Excel XLSX).	`value`	`errorDetails`, nejvyšší `errors`
`VALUE_INVALID`	`validation`	Hodnotu nejde zpracovat: má nesprávný typ nebo formát, nebo odkazuje na záznam, který neexistuje či není dostupný (např. neplatné ID ve výběru).	—	`errorDetails`
`UNKNOWN_FIELD`	`validation`	Vstup obsahuje pole, které operace nezná.	—	`errorDetails`
`VALIDATION_FAILED`	`validation`	Vstup neprošel jinou kontrolou platnosti. Parametr `violation`, je-li uveden, pojmenovává druh kontroly. Hlásí-li jedna chyba víc nevyhovujících hodnot najednou (výpis kontroly objednávky), nemá `field` a `text` uvádí jejich hlášky po řádcích.	`violation`	`errorDetails`
`INVALID_ARGUMENT`	`validation`	Argument operace má neplatnou hodnotu; `field` uvádí jeho název.	—	nejvyšší `errors`
`MISSING_ARGUMENT`	`validation`	Chybí povinný argument operace; `field` uvádí jeho název.	—	nejvyšší `errors`
`REFERENCE_NOT_FOUND`	`not_found`	Záznam, na který vstup odkazuje (např. produkt, sklad, měna nebo objednávka), neexistuje; `field` uvádí odkaz, `id` jeho hodnotu.	`id`	`errorDetails`, nejvyšší `errors`
`DEPOT_MAP_INVALID`	`validation`	Mapa skladu je neplatná: rozměry, meze, překryvy nebo kódy pozic. `element` uvádí druh vadného prvku (`shelf`, `wall`, `position`, `entry`), `index` (regál, stěna) nebo `code` (pozice) určuje který; u překročeného počtu prvků `count` a `limit`, u překročeného rozměru mapy `limit`.	`element`, `index`, `code`, `count`, `limit`	nejvyšší `errors`
`EXPORT_TOO_LARGE`	`validation`	Export by obsahoval víc záznamů, než je povoleno; zvolte menší rozsah.	`count`, `limit`	nejvyšší `errors`
`ORDER_INVALID_INITIAL_STATUS`	`validation`	Objednávku nelze založit v požadovaném stavu (např. Zrušeno).	—	`errorDetails`
`ORDER_CANCELLED`	`business`	Objednávka je zrušená, nelze ji upravovat.	`order`	`errorDetails`
`ORDER_CANCEL_VIA_MUTATION`	`business`	Objednávku nelze zrušit změnou stavu; použijte mutaci `cancelReservation`.	—	`errorDetails`
`ORDER_NOT_RESERVATION`	`business`	Operaci lze provést jen u rezervace a objednávka rezervací není.	—	`errorDetails`
`ORDER_BILL_IMMUTABLE`	`business`	Objednávce ve stavu doklad (`status` = `bill`) už nelze stav změnit.	—	`errorDetails`
`ORDER_ITEM_MOVE_FORBIDDEN`	`business`	Položku nelze přesunout do jiné objednávky.	—	`errorDetails`
`ORDER_ITEM_PACK_NOT_RESERVATION`	`business`	U položky lze upravit jen skladový doklad typu rezervace.	—	`errorDetails`
`ORDER_ITEM_LOCATIONS_SUM_MISMATCH`	`validation`	Součet množství v `locations` mutace `updateClearanceItem` neodpovídá počtu kusů vychystávané položky (`expected`); položka se mohla mezitím změnit, načtěte ji znovu.	`sum`, `expected`	`errorDetails`
`ORDER_DISPATCH_QUANTITY_MISMATCH`	`business`	Počet kusů k vyskladnění nesouhlasí s počtem v objednávce; `product` uvádí produkt položky. (Nesoulad, který způsobil jiný souběžný požadavek, má kód `OPERATION_IN_PROGRESS`.)	`product`	`errorDetails`, nejvyšší `errors`
`ORDER_PROCESS_STATUS_CHANGE_FORBIDDEN`	`business`	Objednávku nelze převést do požadovaného stavu zpracování (`processStatus`): zabalený nebo expedovaný doklad nelze vrátit do fáze před zabalením a doručenou objednávku lze převést jen na vrácenou. `processStatus` uvádí požadovaný stav.	`processStatus`	`errorDetails`, nejvyšší `errors`
`ORDER_BILLED_ITEM_NOT_REMOVABLE`	`business`	Z vyfakturované objednávky (i z objednávky, kterou tatáž mutace vyfakturuje) nelze odebrat ani nahradit položku; `orderItem` uvádí její id. Položky lze přidávat.	`orderItem`	`errorDetails`
`STOCK_INSUFFICIENT`	`business`	Na skladě není dost kusů pro požadované množství.	`requested`, `available`, `product`, `productDepot`, `batch`, `expirationDate`, `position`	`errorDetails`, nejvyšší `errors`
`PRODUCT_DEPOTS_NOT_ALLOWED`	`validation`	U této položky nelze zadat `productDepots`; `reason` uvádí proč: `noProduct` (položka bez produktu), `bundle` (sada), `inPack` (příjmový pohyb, dobropis).	`reason`, `product`	`errorDetails`
`PRODUCT_DEPOT_MISSING`	`validation`	Řádek v `productDepots` neuvádí `productDepot`.	—	`errorDetails`
`PRODUCT_DEPOT_DUPLICATE`	`validation`	Stejný `productDepot` je v `productDepots` uveden vícekrát.	`productDepot`	`errorDetails`
`PRODUCT_DEPOT_QUANTITY_INVALID`	`validation`	Množství u `productDepot` v `productDepots` musí být kladné.	`productDepot`	`errorDetails`
`PRODUCT_DEPOT_WRONG_PRODUCT`	`validation`	Zvolený `productDepot` patří jinému produktu než položka.	`productDepot`, `product`	`errorDetails`
`PRODUCT_DEPOTS_SUM_MISMATCH`	`validation`	Součet množství v `productDepots` (`sum`) neodpovídá množství položky (`expected`).	`sum`, `expected`, `product`	`errorDetails`
`PRODUCT_DEPOT_NOT_FOUND`	`not_found`	Zvolený `productDepot` neexistuje, nebo se pro položku nenašel žádný.	`productDepot`	`errorDetails`
`PRODUCT_DEPOT_DEPOT_NOT_ASSIGNED`	`business`	Sklad zvoleného `productDepot` (u `updateClearanceItem` cílový sklad přesunu) není přiřazen pokladně objednávky.	`depot`, `productDepot`, `order`	`errorDetails`
`PRODUCT_DEPOTS_REQUIRED`	`business`	Rezervace položky je rozdělená mezi víc `productDepot`; při změně množství pošlete `productDepots` s novým rozdělením.	`product`	`errorDetails`
`PRODUCT_DEPOT_REPIN_NOT_RESERVATION`	`business`	Přepnout `productDepot` lze jen u rezervace.	—	`errorDetails`
`PRODUCT_DEPOT_RESERVATION_GONE`	`business`	Rezervace položky byla mezitím zrušena, přeumístění nelze provést.	—	`errorDetails`
`DEPOT_COMPANY_MISMATCH`	`business`	Sklad nepatří ke stejné firmě jako produkt; `field` uvádí argument se skladem (`depotTo`).	—	nejvyšší `errors`
`BUNDLE_CARD_STOCK_FORBIDDEN`	`business`	Sada nevede vlastní sklad: na její kartu nelze naskladnit, vyskladnit ani přeskladnit a nelze smazat pohyb, který by na ni zboží vrátil.	—	`errorDetails`, nejvyšší `errors`
`BUNDLE_NOT_ORDERABLE`	`validation`	Sadu nelze objednat u dodavatele; objednejte jednotlivé produkty sady.	—	`errorDetails`
`BUNDLE_SWITCH_FORBIDDEN`	`business`	Produkt nelze změnit na sadu ani sadu na běžný produkt (`isBundle`), dokud by po změně zůstalo zboží nebo rezervace tam, kde je nikdo nevydá; `reason` uvádí proč: `stock` (produkt má na některém skladu zboží — sada vlastní sklad nevede), `reservations` (produkt nebo sada má otevřené rezervace). `product` uvádí ID produktu. Stávající hodnotu `isBundle` lze poslat vždy.	`reason`, `product`	`errorDetails`
`BUNDLE_CYCLE`	`validation`	Produkt nelze vložit do sady, protože by sada pak obsahovala sama sebe (i přes jiné sady, nebo jde o tentýž produkt). `parent` a `child` uvádějí ID sady a vkládaného produktu, `field` stranu, kterou vstup mění.	`parent`, `child`	`errorDetails`
`PACKAGE_ITEM_ORDER_MISMATCH`	`validation`	Položka nepatří k objednávce balíku: balík smí nést jen položky své objednávky a balík s položkami nelze přesunout k jiné objednávce. Parametr `item` uvádí položku.	`item`	`errorDetails`
`COMPANY_HAS_CHILDREN`	`business`	Firmu s podřízenými firmami nelze smazat.	—	`errorDetails`
`EET_NOT_SUPPORTED`	`business`	EET už není podporováno.	—	`errorDetails`
`CHECKOUT_DEPOT_MISSING`	`business`	Pokladna objednávky nemá přiřazený žádný sklad, skladové pohyby položky nelze vytvořit.	—	`errorDetails`, nejvyšší `errors`
`COMPANY_DEFAULT_SUPPLIER_MISSING`	`business`	Firma nemá nastaveného výchozího dodavatele, který je potřeba k automatickému založení skladové karty produktu (rezervace nebo výdej do mínusu u produktu, který na skladech pokladny kartu nemá).	—	`errorDetails`, nejvyšší `errors`
`ALREADY_EXISTS`	`conflict`	Záznam už existuje; upravte stávající. `id` uvádí jeho ID, je-li známo.	`id`	`errorDetails`
`COMPANY_DELETE_FAILED`	`conflict`	Firmu se nepodařilo smazat; `cause` uvádí kód příčiny.	`cause`	`errorDetails`
`OPERATION_IN_PROGRESS`	`retry`	Stejná data právě mění jiný požadavek. Nic se nezapsalo, požadavek lze poslat znovu.	`productName`, `productDepot`	`errorDetails`, nejvyšší `errors`
`CARRIER_TEST_COOLDOWN`	`retry`	Test u dopravce proběhl před chvílí; zopakujte ho za `retryAfter` sekund.	`retryAfter`	`errorDetails`
`CARRIER_UNAVAILABLE`	`retry`	Spojení s dopravcem se nepodařilo navázat, dopravci nebylo nic odesláno; požadavek lze poslat znovu.	—	`errorDetails`, nejvyšší `errors`
`DB_DEADLOCK`	`outcome_unknown`	Databáze operaci přerušila kvůli souběžnému požadavku (deadlock). Zápis mohl proběhnout, před opakováním načtěte stav.	—	`errorDetails`, nejvyšší `errors`
`DB_LOCK_TIMEOUT`	`outcome_unknown`	Vypršelo čekání na zámek v databázi. Zápis mohl proběhnout, před opakováním načtěte stav.	—	`errorDetails`, nejvyšší `errors`
`DB_CONSTRAINT_VIOLATION`	`outcome_unknown`	Databáze odmítla zápis kvůli integritě dat (duplicita, neplatný nebo chybějící odkaz). Zápis mohl proběhnout, před opakováním načtěte stav.	—	`errorDetails`, nejvyšší `errors`
`DB_ERROR`	`outcome_unknown`	Jiná chyba databáze. Zápis mohl proběhnout, před opakováním načtěte stav.	—	`errorDetails`, nejvyšší `errors`
`CARRIER_OUTCOME_UNKNOWN`	`outcome_unknown`	Spojení s dopravcem selhalo tak, že není jisté, zda u něj zásilka nebo svoz vznikly. Před opakováním ověřte stav.	—	`errorDetails`, nejvyšší `errors`
`CARRIER_SHIPMENT_DATA_INVALID`	`validation`	Údaje zásilky dopravci nestačí (např. položka bez ceny pro celní hodnotu nebo neúplná dodací adresa); zásilka dopravci odeslána nebyla. Parametr `item` uvádí položku, týká-li se chyba položky.	`item`	`errorDetails`, nejvyšší `errors`
`CARRIER_ERROR`	`external`	Dopravce nebo jiná třetí strana požadavek odmítla, vrátila chybu nebo spojení s ní selhalo; `carrier` uvádí dopravce. U odeslání zásilky to nezaručuje, že zásilka u dopravce nevznikla: před opakováním ověřte stav (`CARRIER_OUTCOME_UNKNOWN` vrací jen dopravci, u kterých server nejistý výsledek rozpozná).	`carrier`	`errorDetails`, nejvyšší `errors`
`CARRIER_NOT_CONFIGURED`	`business`	Objednávka ani balík nemají dopravce, pro dopravce neexistuje napojení, nebo firma nemá dopravce nastaveného (chybí relace firmy s dopravcem).	—	`errorDetails`, nejvyšší `errors`
`GRAPHQL_PARSE_FAILED`	`request`	GraphQL dokument nejde přečíst (syntaktická chyba).	—	nejvyšší `errors`
`GRAPHQL_VALIDATION_FAILED`	`request`	GraphQL dokument je neplatný: neznámé pole, chybějící nebo špatně zadaný argument.	—	nejvyšší `errors`
`INTERNAL_ERROR`	`internal`	Chyba na straně serveru.	—	`errorDetails`, nejvyšší `errors`
`BAD_REQUEST`	`request`	Tělo požadavku není platný GraphQL požadavek (HTTP 400). Rezervováno: přichází jen v poli `code` chyby, nikdy v `errorDetails` ani `extensions`.	—	nejvyšší `errors`
`RATE_LIMITED`	`retry`	Požadavek překročil limit využití API (HTTP 429); zopakujte ho po době z hlavičky Retry-After. Rezervováno: přichází jen v poli `code` chyby, nikdy v `errorDetails` ani `extensions`.	—	nejvyšší `errors`
`UNCLASSIFIED`	`unknown`	Chyba zatím nemá přidělený kód; zpracujte ji podle textu.	—	`errorDetails`, nejvyšší `errors`