Chybové kódy

🔴 Chyby většinou chodí s kódem HTTP 200

Stavový kód nestačí

Validace dat, „nenalezeno“, duplicita i konflikt vracejí 200 s success: false. Rozhodujte podle těla odpovědi.

Výjimkou je špatně sestavený požadavek — parametr ve špatném tvaru, nepovolené pole ve filtru. Ten dostane 400 ještě předtím, než se cokoli načte nebo zapíše.

Stavové kódy, které API skutečně používá

Kód	Kdy
200	prakticky vše, včetně aplikačních chyb
204	předběžný CORS dotaz, některé platební návratové adresy
400	parametr ve špatném tvaru, nepovolené pole ve filtru, řazení nebo sloupcích — viz Špatný tvar parametru
401	chybějící nebo neplatný klíč aplikace (kód 501), nebo neplatný, vypršelý či zneplatněný token uživatele (kód 103)
403	zamítnuté oprávnění
404	neexistující zdroj nebo akce — vrací HTML
429	překročený limit aplikace, volajícího, přihlášení nebo obnovy tokenu, s hlavičkou Retry-After
500	neošetřená výjimka — vrací HTML

Kódy výsledku

Číslo v poli code.

Kódy výsledku NEODPOVÍDAJÍ stavovým kódům HTTP

Vypadají podobně a nekorelují. 400 znamená zamítnuté oprávnění, 404 znamená překročený limit, 403 znamená neplatný token.

Nejčastější

Kód	Význam
0	v pořádku
2	validace neprošla — i špatný tvar parametru (pak s HTTP 400)
102	uživatel nenalezen; vrací ho i obnova tokenu u neaktivního, zablokovaného nebo rušeného účtu
103	není přihlášen
104	účet je zablokovaný (hlásí se až po správném hesle)
106	relace vypršela
108	neplatné heslo — i chybějící nebo špatné současné heslo u změny hesla
109	účet není aktivní (hlásí se až po správném hesle)
110	špatné přihlašovací údaje — stejný kód pro neznámý účet i špatné heslo
400	zamítnuté oprávnění
501	chybí platný klíč aplikace (HTTP 401) — API_UNAUTHORIZED
402	přístupový token vypršel
403	přístupový token je neplatný
404	překročený limit požadavků
602	chybí povinné pole
604	hodnota pole se nedá převést na jeho typ — zpráva nese jméno pole
607	nepovolená operace
611	nevyhovující délka — např. nové heslo kratší než 8 znaků
615	nepřípustná hodnota — např. údaj na blacklistu nebo nepovolená kategorie, viz Důvod odmítnutí
616	položka nenalezena

Účet, hesla a odkazy z e-mailu

Kód	Význam
111	aktivační odkaz je neplatný, použitý nebo prošlý (jeden kód i pro neznámý e-mail)
112	odkaz pro obnovu hesla je neplatný, použitý nebo prošlý (jeden kód i pro neznámý e-mail)
113	přihlášení přes cizí službu: e-mail už patří jinému účtu a služba ho nepotvrdila — přihlaste se heslem
114	přihlášení přes cizí službu: nový účet vznikl neaktivní, čeká na aktivaci z e-mailu
115	přihlášení přes cizí službu: propojení s existujícím účtem se musí potvrdit odkazem z e-mailu
116	odkaz pro potvrzení propojení je neplatný, použitý nebo prošlý
117	účet čeká na zrušení — přihlášení je odmítnuté, data nese scheduledAt (datum zrušení)
118	odkaz pro potvrzení nebo storno zrušení účtu je neplatný, použitý nebo prošlý
119	žádost o zrušení účtu bez hesla se potvrzuje odkazem z e-mailu
120	účet byl zrušen a anonymizován — nedá se uložit ani změnit

Kódy 113–119 vznikají hlavně na webu

Přihlášení přes cizí službu a zrušení účtu probíhají na webu a nemají HTTP obal. Přes API se setkáte hlavně s 117 (přihlášení rušeného účtu) a 120 (zápis do zrušeného účtu).

Skupiny

Rozsah	Oblast
100–120	uživatel, přihlášení a účet
200–207	obrázky a soubory
300–304	databáze
400–404	oprávnění a tokeny
500–504	volání API
600–626	data a operace
700–703	úlohy
800–804	zpracování požadavku

Důvod odmítnutí (data.errorCode)

Neúspěšný save, který odmítlo obchodní pravidlo, nese v data jediný klíč errorCode — stálý název důvodu. Kód výsledku (code) určuje skupinu, errorCode konkrétní příčinu. HTTP stav je 200.

{"success":false,"code":615,"message":"Refused: blacklisted …","data":{"errorCode":"blacklisted"}}

code	errorCode	Kdy
2	parameterTooLong	hodnota parametru inzerátu nebo profilu je delší, než parametr dovoluje (u editoru se počítá viditelný text)
2	parameterUrlNotAllowed	hodnota parametru obsahuje odkaz a parametr odkazy zakazuje
2	parameterBlacklistedWord	hodnota parametru obsahuje aktivní zakázané slovo v jazyce stránky požadavku
2	parameterRequired	chybí povinný parametr — povinnost se vyhodnocuje podle pravidel parametrů (např. typ ceny)
2	parameterOptionNotAllowed	zvolená volba výběrového parametru se při ostatních odeslaných hodnotách nenabízí
2	userTypeDataMissing	typ účtu vyžaduje IČ a název firmy nebo DIČ a chybí
2	currencyRequired, currencyNotAllowed	cena odpovědi bez měny, nebo nepovolená měna
400	commentOnlyForLoggedIn	komentář bez přihlášení ve vlákně, kam smějí psát jen přihlášení
607	commentsClosed	komentář do vlákna s vypnutými komentáři
607	advertSold	odpověď na prodaný inzerát
615	blacklisted	e-mail, telefon nebo IP adresa je na blacklistu webu
615	advertCategoryNotAllowed	kategorie inzerátu nebo profilu je vypnutá nebo jen pro administrátora

Podrobnosti jsou jen v textu zprávy

Odpověď nenese číslo parametru, seznam chybějících polí ani typ blokovaného údaje — jen errorCode. Zpráva je zmiňuje (parameter #12, regId, companyName), ale její text se může změnit. Rozhodujte podle code a errorCode.

extend-expiration v placené kategorii vrací jen kód

Akce advert/extend-expiration (inzerce i firmy) odmítne neprivilegovanému volajícímu prodloužení v placené kategorii s code: 607 a data: null — důvod (paymentRequired) je jen v textu zprávy. Prodloužení v placené kategorii se platí na webu.

Administrátor se nekontroluje

Pravidla platí pro neprivilegovaného volajícího (host, přihlášený uživatel, vlastník). Aplikace jednající s rolí admin je obchází stejně jako administrace webu.

Ukázky

Chybí platný klíč aplikace (HTTP 401) — stejná odpověď pro chybějící, špatný, vypnutý i zrušený klíč:

{"success":false,"message":"A valid application key (X-API-Key) is required.","data":null,"code":501}

Neplatný token uživatele (HTTP 401, token neplatí, vypršel nebo byl zneplatněn):

{"success":false,"message":"Authentication required","data":null,"code":103}

Zamítnuto (HTTP 403):

{"success":false,"message":"Permission denied","data":null,"code":400}

Limit aplikace nebo volajícího (HTTP 429, hlavička Retry-After: 3):

{"success":false,"message":"Too many requests.","data":{"retryAfter":3},"code":404}

Limit přihlášení nebo obnovy tokenu (HTTP 429, hlavička Retry-After: 240) — tytéž klíče, jen zpráva nese i počet sekund:

{"success":false,"message":"Too many requests, retry in 240s","data":{"retryAfter":240},"code":404}

Počkejte Retry-After sekund. Rozhodujte podle code a data.retryAfter, ne podle textu zprávy.

Chybí data (HTTP 200):

{"success":false,"code":602,"message":"Missing data"}

Poslední ukázka nemá klíč data

Obálka není konzistentní. Čtěte jednotlivé klíče obranně.

Nepřevoditelná hodnota (HTTP 200):

{"success":false,"code":604,"message":"Invalid value for field \"currencyId\": expected int, got \"1.9\"."}

Příliš mnoho nových záznamů (HTTP 200, bez Retry-After):

{"success":false,"message":"Too many new records, try again later.","data":null,"code":404}

Vrací ho uložení nového obsahu nad kvótou zakládání.

Maskovaná technická chyba (errorRef)

Technické selhání (databáze, soubory, externí služba, fronta, neznámá chyba) neprozradí v odpovědi nic o vnitřku systému. Místo textu výjimky přijde obecná hláška a referenční kód:

{"success":false,"code":300,"message":"An internal error occurred. Quote the reference when contacting support.","errorRef":"3f9a1c07","data":null}

Kód errorRef předejte správci webu — v logu serveru je pod [errorRef=3f9a1c07] celý detail. Klient se podle textu message neřídí; rozhoduje code. Doménové chyby (validace, stav, nenalezeno) errorRef nemají a jejich message se nemění.

Špatný tvar parametru

Parametr, který má jiný tvar, než akce čeká, se nepřetypuje — požadavek skončí HTTP 400 s kódem 2, dřív než se cokoli načte nebo zapíše:

{"success":false,"message":"Invalid shape of request parameter \"filters\".","data":null,"code":2}

Příklad	Proč neprojde
filters=x, orderBys=x, columns=x	text místo pole
data=x, meta=x, skipFields=x u save	text místo pole
ids u update-columns chybí, je prázdné nebo je to text; values je text	seznam ID a hodnoty musí být pole
ids u register-event není neprázdný seznam kladných celých čísel	1.9, 0 ani prázdný seznam neprojdou
computeTotalCount=ano	logická hodnota jen 1/0, true/false, on/off
includes[0][]=user, includes=	includes je jedna cesta nebo seznam cest
includes=* nebo columns[]=… u get-all	u výpisu se nepodporují
filtr s neznámým typem, bez pole nebo s vnořenou skupinou ve špatném tvaru	filtr se nedá sestavit
doplňkový klíč filtru inclusive nebo isNull poslaný v adrese	očekává se pravdivostní hodnota, adresa nese jen text

Nepovolené pole ve filtru má vlastní zprávu

Filtr, řazení nebo sloupec nad polem, které volající nesmí číst (heslo, IP adresa, e-mail cizího uživatele, neexistující pole), vrátí také HTTP 400 a kód 2, se zprávou Field path "user.email" is not allowed in filters, orderBys or columns. Podrobně v Oprávněních.

400 je chyba klienta — opakování nepomůže

Opravte sestavení požadavku. Zpráva říká, který parametr je špatně.

Nastavení cookies