Chyby

Každá chybová odpověď z /api/v1/* obsahuje stabilní, strojově čitelné pole code. Partneři filtrují podle code, nikoliv podle HTTP statusu (statusy jsou sdíleny mezi více kódy) a nikoliv podle message (která je lokalizovaná). Prostor kódů je append-only: kód, který je jednou vydán, není nikdy přejmenován, přečíslován ani odstraněn.

Obálka

Typická odpověď 400:

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

code: jedna z hodnot v katalogu níže. Filtrujte podle tohoto pole.
message: lidsky čitelný popis, lokalizovaný podle hlavičky Accept-Language volajícího (výchozí je hr). Neparsujte toto pole programově.
errors: přítomno v odpovědích VALIDATION_FAILED. Slovník, kde klíčem je název pole a hodnotou je pole lokalizovaných zpráv pro dané pole.

Chyby serveru (HTTP 500) vynechávají slovník errors a nesou obecnou zprávu. Opakujte požadavek s využitím back-off; pokud chyba přetrvává, kontaktujte podporu s ID požadavku (viditelné v hlavičce odpovědi X-Request-Id, pokud je přítomna).

Katalog

Kód	HTTP	Kdy nastane	Reakce partnera
`VALIDATION_FAILED`	400	Tělo požadavku neprošlo validací nebo chybí povinná hlavička.	Zkontrolujte slovník `errors`. Zobrazte zprávy na úrovni polí koncovému uživateli.
`EXCHANGE_RATE_UNAVAILABLE`	400	Poskytovatel měnových kurzů tenanta nezveřejňuje žádný kurz pro danou měnu v požadovaném datu a neexistuje žádný historický kurz, na který by se dalo spolehnout.	Selhání z rodiny validací s tělem `errors` klíčovaným podle polí. Vyzvěte uživatele k ručnímu zadání kurzu, nebo vyberte měnu, kterou poskytovatel oceňuje.
`UNAUTHORIZED`	401	API klíč chybí, je chybně naformátován nebo byl odvolán.	Zkontrolujte hlavičku `Authorization`. Pokud byl klíč odvolán, vystavte jej znovu.
`API_ACCESS_NOT_ENABLED`	402	Cílová společnost nemá v předplatném funkci `ApiAccess`.	Upgradujte společnost na Enterprise, nebo přidejte doplněk `ApiAccess` v nastavení fakturace.
`FORBIDDEN`	403	Ověřeno, ale uživatel, který klíč vydal, nemá oprávnění pro operaci v tomto rozsahu.	Zkontrolujte roli jednajícího uživatele v cílové společnosti. Vystavte klíč znovu jako administrátor.
`NOT_FOUND`	404	Cílový zdroj neexistuje nebo byl smazán.	Ověřte id. Zdroj mohl být odstraněn jiným aktérem.
`CONFLICT`	409	Duplicitní zdroj, neaktuální předpoklad nebo opakování `idempotency-key` s jiným tělem.	Slaďte stav. Opakování může uspět s jiným payloadem, nebo může vyžadovat no-op.
`RATE_LIMIT_EXCEEDED`	429	Byl překročen limit požadavků na klíč (za sekundu, za hodinu nebo za den).	Použijte back-off podle hlavičky `Retry-After`. Viz Omezení rychlosti.
`KEY_REVOKED`	401	Vyhrazeno pro budoucí vlastní challenge handler. V současnosti se neemituje.	Připravte si svůj handler. Dnes tok s odvolaným klíčem vrací čisté HTTP 401.
`INTERNAL_ERROR`	500	Neošetřená chyba serveru.	Opakujte s exponenciálním back-off. Pokud chyba přetrvává, kontaktujte podporu.

Záruka append-only

Jakmile je kód vydán, zůstává v katalogu navždy, i když je jeho původce smazán. Partneři se mohou spolehnout, že se jejich switch příkazy pro code nikdy tiše nerozbijí kvůli tomu, že by locco přejmenovalo hodnotu. Pokud se chování kolem kódu změní (jiný HTTP status, nové omezení), je to uvedeno v changelogu; samotný řetězec kódu zůstává stabilní.

Partnerům doporučujeme zpracovávat neznámé kódy defenzivně: pokud je vydán nový kód dříve, než je váš klient aktualizován, považujte jej za obecné selhání (pravděpodobně ve tvaru INTERNAL_ERROR) a zaznamenejte surovou odpověď pro pozdější kontrolu, místo aby aplikace spadla.