Chyby a limity

Tvar chyby

Obe API používajú rovnaký tvar chyby na úrovni požiadavky:

{ "error": "invalid_key", "message": "Unknown or malformed public key." }

error je stabilný kód určený na programové vetvenie. message je anglický text pre človeka; jeho znenie sa môže zmeniť, preto naň neviažte logiku aplikácie.

kód	HTTP	čo s tým
missing_key	401	v query chýba parameter key (Search API)
invalid_key	403	neznámy alebo nesprávne sformovaný verejný kľúč
invalid_credentials	401	chýbajúca alebo neplatná hlavička Authorization (Catalog API)
insecure_transport	400	požiadavka so secret kľúčom prišla cez HTTP (Catalog API); použite HTTPS
invalid_parameter	422	nepodporovaná hodnota parametra (sort, include, per_page, limit, image_size, cena), neznámy parameter alebo chybný filter pri /search, alebo stránka za hranicou 200 výsledkov
invalid_payload	400	telo nie je platný JSON, nie je zoznamom produktov alebo neobsahuje ids
batch_too_large	400	dávka obsahuje viac než 100 produktov
catalog_mode_conflict	409	e-shop je v režime feed, zápisy sú zakázané
generation_incomplete, generation_committed	409	commit syncu neprešiel poistkou; generation_committed aj pri zápise s ?sync= do už commitnutého syncu
not_found	404	neznámy identifikátor syncu, aj pri zápise s ?sync=
index_busy	503	vyhľadávací index e-shopu je zaneprázdnený; nič sa nezapísalo, zopakujte po Retry-After
rate_limited	429	prekročený limit; riaďte sa hlavičkou Retry-After

Chyby jednotlivých produktov

Tieto kódy nevracia požiadavka ako celok, ale jednotlivá položka v poli results pri PUT, PATCH a DELETE:

kód	príčina
invalid_id	id chýba, je prázdne alebo presahuje 255 znakov
missing_name, missing_url	pri PUT chýba povinné pole
invalid_name, invalid_brand, invalid_description	pole nie je neprázdny reťazec
invalid_url, invalid_image	pole nie je https URL do 2048 znakov (napríklad http://, relatívna cesta, javascript:)
invalid_price, invalid_list_price	cena nie je JSON number, napríklad prišla ako reťazec
invalid_in_stock	in_stock nie je boolean
invalid_params	params nie je mapou názov → skalárna hodnota alebo je názov prázdny či príliš dlhý
invalid_category	prázdna cesta kategórie
not_found	PATCH alebo DELETE smeroval na neexistujúci produkt

Rate limity

endpoint	limit
GET /suggest	1800 / min
GET /search	600 / min
/catalog/*	120 / min

Limity /search a /suggest sa počítajú na IP adresu volajúceho: verejný kľúč vidí každý návštevník e-shopu, takže volajúceho neidentifikuje. Keď Search API voláte zo svojho servera, všetky požiadavky z neho zdieľajú jeden limit. Do limitu /search pre IP návštevníka sa počíta aj widget, takže prehliadač, v ktorom beží widget a zároveň priamo volá GET /search, zdieľa jeden limit 600 / min. Limit /catalog/* sa počíta na secret kľúč, takže jeden integrátor neovplyvní ostatných. Väčšia dávka spotrebuje viac: k jednému tokenu sa pripočíta ďalší za každých 256 KB tela požiadavky.

Pri prekročení limitu vrátime 429 s hlavičkami Retry-After, X-RateLimit-Limit a X-RateLimit-Remaining.

Odporúčaná stratégia opakovania

• 429 — počkajte podľa hlavičky Retry-After a požiadavku zopakujte.
• 5xx — zopakujte s exponenciálnym backoffom.
• ostatné 4xx — opakovanie nepomôže, požiadavku treba opraviť.

Opakovanie zápisovej dávky je bezpečné, pretože zápis prebieha podľa id.