Chyby a limity

Tvar chyby

Každá chyba na úrovni requestu má rovnaký tvar:

{ "error": { "code": "invalid_credentials", "message": "Missing or invalid secret key." } }

kód	HTTP	čo s tým
invalid_credentials	401	chýbajúci alebo zlý secret_key
insecure_transport	400	request išiel cez HTTP; použi HTTPS
catalog_mode_conflict	409	e-shop je v režime feed
invalid_payload	400	telo nie je platný JSON alebo nie je zoznam objektov
batch_too_large	400	viac než 100 objektov v dávke
invalid_query	400	nepodporovaný parameter alebo facet
not_found	404	neznámy api_key, náhľad alebo generácia
rate_limited	429	prekročený limit, pozri Retry-After

Chyby jednotlivých objektov

Tieto nevracia request, ale položka v poli objects:

kód	príčina
invalid_identity	prázdna alebo príliš dlhá identity
missing_field	chýba povinné pole (type, title, web_url)
invalid_field	zlý typ hodnoty — napr. cena ako string
invalid_attribute_name	názov atribútu s bodkou alebo zátvorkou
unsupported_type	iný typ než item / product
nested_unsupported	objekt obsahuje nested
not_found	PATCH alebo DELETE na neexistujúci objekt

Rate limity

endpoint	limit
GET /autocomplete/v2	1800 / min
GET /search, GET /v1/facet_value	600 / min
/v1/content*	120 / min

Limit sa počíta na api_key (pri zápisoch na secret_key), takže jeden integrátor neovplyvní ostatných. Veľká dávka stojí viac než malá — počíta sa aj veľkosť payloadu.

Pri prekročení príde 429 s hlavičkami Retry-After, X-RateLimit-Limit a X-RateLimit-Remaining.

Ako opakovať request

• 429 — počkaj podľa Retry-After a skús znova.
• 5xx — skús znova s exponenciálnym backoffom.
• ostatné 4xx — opakovanie nepomôže, oprav request.

Opakovanie zápisovej dávky je bezpečné, lebo zapisuje podľa identity. Hotové to má PHP klient.