Chyby

Každá chybová odpoveď z /api/v1/* obsahuje stabilné, strojom čitateľné pole code. Partneri filtrujú podľa code, nie podľa HTTP statusu (statusy sú zdieľané medzi viacerými kódmi) a nie podľa message (ktorá je lokalizovaná). Priestor kódov je append-only: kód, ktorý je raz vydaný, sa nikdy nepremenuje, neprečísluje ani neodstráni.

Obálka

Typická 400 odpoveď:

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

code: jedna z hodnôt v katalógu nižšie. Filtrujte podľa tohto.
message: ľudsky čitateľný popis, lokalizovaný podľa hlavičky volajúceho Accept-Language (predvolená hodnota je hr). Neparsujte to programaticky.
errors: prítomné v odpovediach VALIDATION_FAILED. Slovník, kde kľúčom je názov poľa a hodnotou je pole lokalizovaných správ pre dané pole.

Chyby servera (HTTP 500) vynechávajú slovník errors a nesú všeobecnú správu. Zopakujte požiadavku s oneskorením (back-off); ak chyba pretrváva, kontaktujte podporu s ID požiadavky (viditeľné v hlavičke odpovede X-Request-Id, ak je prítomná).

Katalóg

Code	HTTP	Kedy nastane	Reakcia partnera
`VALIDATION_FAILED`	400	Telo požiadavky neprešlo validáciou alebo chýba povinná hlavička.	Skontrolujte slovník `errors`. Zobrazte správy na úrovni polí koncovému používateľovi.
`EXCHANGE_RATE_UNAVAILABLE`	400	Poskytovateľ FX pre tenanta nezverejňuje žiadny kurz pre danú menu v požadovanom dátume a neexistuje žiadny historický kurz, na ktorý by sa dalo spoľahnúť.	Zlyhanie z rodiny validácií s telom `errors` kľúčovaným podľa polí. Vyzvite používateľa na manuálne zadanie kurzu alebo vyberte menu, ktorú poskytovateľ oceňuje.
`UNAUTHORIZED`	401	API kľúč chýba, je nesprávne naformátovaný alebo bol odvolaný.	Skontrolujte hlavičku `Authorization`. Ak bol kľúč odvolaný, vydajte ho znova.
`API_ACCESS_NOT_ENABLED`	402	Cieľová spoločnosť nemá funkciu predplatného `ApiAccess`.	Inovujte spoločnosť na Enterprise alebo pridajte doplnok `ApiAccess` v nastaveniach fakturácie.
`FORBIDDEN`	403	Autentifikované, ale používateľ, ktorý kľúč vydal, nemá oprávnenie na operáciu v tomto rozsahu.	Skontrolujte rolu konajúceho používateľa v cieľovej spoločnosti. Znova vydajte kľúč ako administrátor.
`NOT_FOUND`	404	Cieľový zdroj neexistuje alebo bol vymazaný.	Overte ID. Zdroj mohol byť odstránený iným aktérom.
`CONFLICT`	409	Duplicitný zdroj, neaktuálna podmienka alebo opakovanie `idempotency-key` s iným telom.	Zosúlaďte stav. Opakovanie môže uspieť s iným payloadom alebo môže vyžadovať no-op.
`RATE_LIMIT_EXCEEDED`	429	Bol prekročený limit počtu požiadaviek na kľúč (za sekundu, za hodinu alebo za deň).	Počkajte podľa hlavičky `Retry-After`. Pozrite si Rate limits.
`KEY_REVOKED`	401	Vyhradené pre budúci vlastný challenge handler. Momentálne sa neemituje.	Pripravte si svoj handler. Dnes tok odvolaného kľúča vracia čistý HTTP 401.
`INTERNAL_ERROR`	500	Nespracovaná chyba servera.	Zopakujte požiadavku s exponenciálnym oneskorením. Ak chyba pretrváva, kontaktujte podporu.

Záruka append-only

Akonáhle je kód vydaný, zostáva v katalógu navždy, aj keď je jeho emitent vymazaný. Partneri sa môžu spoľahnúť, že ich switch príkazy pre code sa nikdy potichu nepokazia kvôli tomu, že locco premenovalo hodnotu. Ak sa správanie okolo kódu zmení (iný HTTP status, nové obmedzenie), je to uvedené v changelogu; samotný reťazec kódu zostáva stabilný.

Partnerom sa odporúča spracovávať neznáme kódy defenzívne: ak je vydaný nový kód predtým, ako je váš klient aktualizovaný, zaobchádzajte s ním ako so všeobecným zlyhaním (pravdepodobne vo forme INTERNAL_ERROR) a zaznamenajte si surovú odpoveď na neskoršie preskúmanie namiesto toho, aby aplikácia spadla.