Napake

Vsak odgovor z napako iz /api/v1/* vsebuje stabilno, strojno berljivo polje code. Partnerji filtrirajo po code, ne po HTTP statusu (statusi so deljeni med več kodami) in ne po message (ki je lokaliziran). Nabor kod je le dodajen: koda, ki je enkrat dostavljena, se nikoli ne preimenuje, prenumeriraja ali odstrani.

Ovojnica

Tipičen odgovor 400:

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

code: ena od vrednosti v katalogu spodaj. Filtrirajte po tem.
message: berljiv opis, lokaliziran na Accept-Language klicatelja (privzeto hr). Ne razčlenjujte ga programsko.
errors: prisotno v odgovorih VALIDATION_FAILED. Slovar s ključem po imenu polja in nizom lokaliziranih sporočil po polju.

Napake strežnika (HTTP 500) izpustijo slovar errors in vsebujejo generično sporočilo. Poskusite znova z zakasnitvijo; če se napaka ponavlja, kontaktirajte podporo z ID-jem zahtevka (viden v glavi odgovora X-Request-Id, kjer je na voljo).

Katalog

Koda	HTTP	Kdaj se pojavi	Partnerjev odziv
`VALIDATION_FAILED`	400	Telo zahtevka ni prestalo preverjanja, ali manjka obvezna glava.	Preglejte slovar `errors`. Sporočila po poljih prikažite končnemu uporabniku.
`EXCHANGE_RATE_UNAVAILABLE`	400	Ponudnik tečaja tenanta ne objavi tečaja za valuto na zahtevani datum in ni zgodovinskega tečaja, na katerega bi se lahko zanesli.	Napaka iz družine preverjanj s telesom `errors` po poljih. Od uporabnika zahtevajte ročni tečaj ali izberite valuto, ki jo ponudnik kotira.
`UNAUTHORIZED`	401	API ključ manjka, je nepravilen ali je preklican.	Preverite glavo `Authorization`. Izdajte nov ključ, če je preklican.
`API_ACCESS_NOT_ENABLED`	402	Ciljno podjetje nima naročniške funkcije `ApiAccess`.	Nadgradite podjetje na Enterprise v nastavitvah obračuna.
`FORBIDDEN`	403	Avtenticirani ste, vendar izdajatelj ključa nima dovoljenja za operacijo v tem obsegu.	Preverite vlogo uporabnika v ciljnem podjetju. Izdajte ključ kot administrator.
`NOT_FOUND`	404	Ciljni vir ne obstaja ali je izbrisan.	Preverite ID. Vir je morda odstranil drug akter.
`CONFLICT`	409	Podvojen vir, zastarel pogoj ali idempotency-key replay z drugačnim telesom.	Uskladite stanje. Ponovni poskus lahko uspe z drugačno vsebino ali zahteva no-op.
`RATE_LIMIT_EXCEEDED`	429	Preseženo je okno omejitve po ključu (na sekundo, uro ali dan).	Zakasnite zahtevek po glavi `Retry-After`. Glej Omejitve zahtevkov.
`KEY_REVOKED`	401	Rezervirano za prihodnje ravnanje s preklici. Trenutno se ne oddaja.	Pripravite svoj handler vnaprej. Trenutno preklican ključ vrne goli HTTP 401.
`INTERNAL_ERROR`	500	Neobdelana napaka strežnika.	Poskusite znova z eksponentno zakasnitvijo. Če se napaka ponavlja, kontaktirajte podporo.

Jamstvo nepreimenovanja

Ko je koda enkrat dostavljena, ostane v katalogu za vedno, tudi če je njen oddajatelj izbrisan. Partnerji se lahko zanesejo, da se njihovi switch izrazi po code ne bodo tiho zlomili, ker je locco preimenoval vrednost. Če se vedenje okoli neke kode spremeni (drug HTTP status, nova omejitev), je to navedeno v dnevniku sprememb; sam niz kode ostane stabilen.

Partnerjem priporočamo obrambno ravnanje z neznanimi kodami: če nova koda prispe, preden je vaš odjemalec posodobljen, jo obravnavajte kot generično napako (verjetno v obliki INTERNAL_ERROR) in surov odgovor logirajte za poznejšo analizo, namesto da se odjemalec zruši.