Chyby

Keď požiadavka na API zlyhá, badges.ninja vráti chybovú odpoveď JSON s príslušným stavovým kódom HTTP.

Formát chyby

Všetky chyby majú túto štruktúru:

{
  "error": "description of what went wrong"
}

Stavové kódy

Kód	Význam	Kedy nastane
400	Nesprávna požiadavka	Chýbajúce alebo neplatné parametre, dosiahnutý limit plánu alebo kvóta, funkcia vyžaduje vyšší plán alebo chýba autorizácia — všetky zlyhania validácie vracajú 400
402	Vyžaduje sa platba	Vyhradené pre vyčerpanie kreditov. API badges momentálne kredity neodpočítava, takže tento kód sa v praxi nikdy nevracia
404	Nenájdené	Požadovaný zdroj neexistuje
500	Interná chyba servera	Na serveri nastala neočakávaná chyba

Kódy 403 ani 429 neexistujú: zlyhania autorizácie vracajú 400 („not authorized“) a na aplikačnej úrovni sa neuplatňuje žiadne obmedzenie frekvencie požiadaviek.

Bežné chyby a riešenia

Chýbajúce povinné parametre

{ "error": "missing required parameters: name, url, email" }

Riešenie: Zahrňte do tela požiadavky všetky povinné parametre. Úplný zoznam nájdete v dokumentácii endpointu.

Neplatný e-mail

{ "error": "invalid email" }

Riešenie: Zadajte platnú e-mailovú adresu vo formáte user@domain.com.

Neplatná URL

{ "error": "invalid URL" }

Riešenie: Zadajte úplnú URL vrátane protokolu, napr. https://example.com.

Príliš krátky názov

{ "error": "name must be at least 3 characters" }

Riešenie: Použite dlhší názov. Názvy vydavateľov vyžadujú aspoň 3 znaky. Mená príjemcov vyžadujú aspoň 5 znakov.

Vydavateľ nie je overený

{ "error": "issuer must be verified before creating badges" }

Riešenie: Najprv overte vydavateľa. Skontrolujte e-mail vydavateľa, kde nájdete overovací odkaz, alebo použite endpoint Overenie vydavateľa.

Dosiahnutá kvóta poverení (400)

{ "error": "Your Free plan reached its credential limit (1200/1200) — your allowance renews on your plan anniversary, or upgrade to Starter" }

Riešenie: Vyčerpali ste celý ročný fond poverení (Free: 1 200 ročne, Starter: 12 000 ročne, Pro: 120 000 ročne). Fond sa obnovuje v deň výročia registrácie vášho účtu — nie na hranici kalendárneho mesiaca. Pre vyšší limit prejdite na vyšší plán. Pozrite si Plány a fakturácia.

Dosiahnutý limit plánu (400)

{ "error": "Your Free plan reached its issuer limit (2/2) — delete an issuer or upgrade to Starter" }

Limit odznakov má rovnaký tvar:

{ "error": "badge limit reached (5/5 on the starter plan) — delete a badge or upgrade your plan" }

Riešenie: Dosiahli ste limit svojho plánu pre vydavateľov alebo odznaky. Odstráňte nepoužívaný zdroj alebo prejdite na vyšší plán.

Zdroj má závislosti (400)

{ "error": "issuer has 3 badge(s) linked — delete the badges first" }

Riešenie: Pred odstránením vydavateľa odstráňte všetky odznaky, ktoré sú s ním prepojené. Rovnako pred odstránením odznaku odstráňte všetky poverenia pod týmto odznakom.

Neautorizované (400)

{ "error": "not authorized" }

Zlyhania autorizácie sú chyby validácie, preto vracajú 400 (nie 401 ani 403).

Riešenie: Upravovať môžete iba zdroje, ktoré vlastníte. Uistite sa, že používate správny kľúč API.

HTML v texte na zdieľanie

{ "error": "HTML tags are not allowed" }

Riešenie: Text na zdieľanie musí byť obyčajný text. Odstráňte z parametra text všetky HTML značky.