Greške

Svaki odgovor s greškom iz /api/v1/* sadrži stabilno, strojno čitljivo polje code. Partneri filtriraju po code, a ne po HTTP statusu (statusi se dijele između više kodova) i ne po message (koji je lokaliziran). Skup kodova je samo dodatan: kod koji jednom bude isporučen nikada se ne preimenuje, prenumerira ili ukloni.

Omotnica

Tipičan odgovor 400:

{
  "code": "VALIDATION_FAILED",
  "message": "Name is required.",
  "errors": { "name": ["Name is required."] }
}

code: jedna od vrijednosti u katalogu ispod. Filtrirajte po ovome.
message: čitljiv opis, lokaliziran na pozivateljev Accept-Language (zadano hr). Ne parsirajte ga programatski.
errors: prisutno na odgovorima VALIDATION_FAILED. Rječnik s ključem po nazivu polja i nizom lokaliziranih poruka po polju.

Greške servera (HTTP 500) izostavljaju rječnik errors i sadrže generičku poruku. Pokušajte ponovno s odgodom; ako se greška ponavlja, kontaktirajte podršku s ID-jem zahtjeva (vidljiv u zaglavlju odgovora X-Request-Id gdje je dostupan).

Katalog

Kod	HTTP	Kada se javlja	Partnerov odgovor
`VALIDATION_FAILED`	400	Tijelo zahtjeva nije prošlo provjeru, ili nedostaje obavezno zaglavlje.	Pregledajte rječnik `errors`. Prikažite poruke po poljima krajnjem korisniku.
`UNAUTHORIZED`	401	API ključ nedostaje, neispravan je ili je opozvan.	Provjerite zaglavlje `Authorization`. Izdajte novi ključ ako je opozvan.
`API_ACCESS_NOT_ENABLED`	402	Ciljana tvrtka nema pretplatničku značajku `ApiAccess`.	Nadogradite na Enterprise ili dodajte `ApiAccess` na trenutni paket u postavkama naplate.
`FORBIDDEN`	403	Autenticirani ste, ali izdavač ključa nema dozvolu za operaciju u ovom opsegu.	Provjerite ulogu korisnika u ciljanoj tvrtki. Izdajte ključ kao administrator.
`NOT_FOUND`	404	Ciljani resurs ne postoji ili je obrisan.	Provjerite ID. Resurs je možda uklonio drugi akter.
`CONFLICT`	409	Duplicirani resurs, zastarjeli preduvjet ili idempotency-key replay s drugačijim tijelom.	Uskladite stanje. Ponovni pokušaj može uspjeti s drugim sadržajem ili zahtijevati no-op.
`RATE_LIMIT_EXCEEDED`	429	Premašen je prozor ograničenja po ključu (po sekundi, po satu ili po danu).	Odgodite zahtjev prema zaglavlju `Retry-After`. Vidi Ograničenja zahtjeva.
`KEY_REVOKED`	401	Rezervirano za buduće rukovanje s opozivima. Trenutno se ne emitira.	Pripremite svoj handler unaprijed. Trenutno opozvani ključ vraća goli HTTP 401.
`INTERNAL_ERROR`	500	Neobrađena greška servera.	Pokušajte ponovno s eksponencijalnom odgodom. Ako se greška ponavlja, kontaktirajte podršku.

Jamstvo nepreimenovanja

Jednom kada je isporučen, kod ostaje u katalogu zauvijek, čak i ako njegov emiter bude obrisan. Partneri se mogu osloniti da im se switch izrazi po code neće tiho slomiti jer je locco preimenovao vrijednost. Ako se ponašanje oko nekog koda promijeni (drugi HTTP status, novo ograničenje), to se navodi u dnevniku promjena; sam string koda ostaje stabilan.

Partnerima se preporučuje obrambeno rukovanje nepoznatim kodovima: ako novi kod stigne prije nego što je vaš klijent ažuriran, tretirajte ga kao generičku grešku (vjerojatno oblika INTERNAL_ERROR) i logirajte sirovi odgovor za kasniju analizu, umjesto da se klijent sruši.