Chyby

Když požadavek API selže, badges.ninja vrací JSON odpověď s chybou a odpovídajícím HTTP status kódem.

Formát chyby

Všechny chyby mají tuto strukturu:

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

Stavové kódy

Kód	Význam	Kdy nastává
400	Bad Request	Chybějící nebo neplatné parametry, dosažený limit plánu nebo kvóty, funkce vyžaduje vyšší plán, nebo chybějící oprávnění — všechna selhání validace vracejí 400
402	Payment Required	Vyhrazeno pro vyčerpání kreditů. API odznaků v současnosti kredity neodečítá, takže se tento kód v praxi nikdy nevrací
404	Not Found	Požadovaný zdroj neexistuje
500	Internal Server Error	Na serveru došlo k neočekávané chybě

Kódy 403 ani 429 neexistují: selhání autorizace vracejí 400 („not authorized“) a na aplikační vrstvě se neuplatňuje žádné omezování četnosti požadavků.

Časté chyby a řešení

Chybějící povinné parametry

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

Řešení: Zahrňte do těla požadavku všechny povinné parametry. Úplný seznam najdete v dokumentaci příslušného endpointu.

Neplatný e-mail

{ "error": "invalid email" }

Řešení: Zadejte platnou e-mailovou adresu ve formátu user@domain.com.

Neplatná URL

{ "error": "invalid URL" }

Řešení: Zadejte úplnou URL včetně protokolu, např. https://example.com.

Příliš krátký název

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

Řešení: Použijte delší název. Názvy vydavatelů vyžadují alespoň 3 znaky. Jména příjemců vyžadují alespoň 5 znaků.

Vydavatel není ověřen

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

Řešení: Nejprve ověřte vydavatele. Vyhledejte ověřovací odkaz v e-mailu vydavatele nebo použijte endpoint Ověřit vydavatele.

Dosažena kvóta pověření (400)

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

Řešení: Vyčerpali jste celý roční fond pověření (Free: 1 200/rok, Starter: 12 000/rok, Pro: 120 000/rok). Fond se obnovuje v den výročí registrace vašeho účtu — nikoli na hranici kalendářního měsíce. Pro vyšší limit přejděte na vyšší plán. Viz Plány a fakturace.

Dosažen limit plánu (400)

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

Limit odznaků má stejný tvar:

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

Řešení: Dosáhli jste limitu svého plánu pro vydavatele nebo odznaky. Smažte nepoužívaný zdroj nebo přejděte na vyšší plán.

Zdroj má závislosti (400)

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

Řešení: Před smazáním vydavatele smažte všechny odznaky s ním spojené. Podobně před smazáním odznaku smažte všechna pověření pod tímto odznakem.

Neautorizováno (400)

{ "error": "not authorized" }

Selhání autorizace jsou chyby validace, proto vracejí 400 (nikoli 401 ani 403).

Řešení: Upravovat můžete pouze zdroje, které vlastníte. Ujistěte se, že používáte správný API klíč.

HTML v textu ke sdílení

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

Řešení: Text ke sdílení musí být prostý text. Odstraňte z parametru text všechny HTML značky.