Napake

Ko zahtevek API ne uspe, badges.ninja vrne odgovor z napako v obliki JSON z ustrezno kodo stanja HTTP.

Oblika napake

Vse napake imajo to strukturo:

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

Kode stanja

Koda	Pomen	Kdaj se zgodi
400	Bad Request	Manjkajoči ali neveljavni parametri, dosežena omejitev paketa ali kvota, funkcija zahteva višji paket ali ni pooblastila — vse napake pri preverjanju vrnejo 400
402	Payment Required	Rezervirano za porabo kreditov. API za značke trenutno ne odšteva kreditov, zato se ta koda v praksi nikoli ne vrne
404	Not Found	Zahtevani vir ne obstaja
500	Internal Server Error	Na strežniku je prišlo do nepričakovane napake

Kod 403 in 429 ni: napake pooblastil vrnejo 400 ("not authorized"), omejevanja hitrosti na aplikacijski ravni pa ni.

Pogoste napake in rešitve

Manjkajoči obvezni parametri

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

Rešitev: V telo zahtevka vključite vse obvezne parametre. Celoten seznam najdete v dokumentaciji končne točke.

Neveljaven e-poštni naslov

{ "error": "invalid email" }

Rešitev: Vnesite veljaven e-poštni naslov v obliki user@domain.com.

Neveljaven URL

{ "error": "invalid URL" }

Rešitev: Vnesite poln URL skupaj s protokolom, npr. https://example.com.

Prekratko ime

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

Rešitev: Uporabite daljše ime. Imena izdajateljev morajo imeti vsaj 3 znake. Imena prejemnikov morajo imeti vsaj 5 znakov.

Izdajatelj ni preverjen

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

Rešitev: Najprej preverite izdajatelja. Poiščite povezavo za preverjanje v e-pošti izdajatelja ali uporabite končno točko Preverjanje izdajatelja.

Dosežena kvota poverilnic (400)

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

Rešitev: Porabili ste celoten letni sklad poverilnic (Free: 1.200/leto, Starter: 12.000/leto, Pro: 120.000/leto). Sklad se ponastavi na obletnico registracije vašega računa — ne na mejo koledarskega meseca. Za višjo kvoto nadgradite paket. Glejte Paketi in obračunavanje.

Dosežena omejitev paketa (400)

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

Omejitev števila značk ima enako obliko:

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

Rešitev: Dosegli ste zgornjo mejo paketa za izdajatelje ali značke. Izbrišite neuporabljen vir ali nadgradite paket.

Vir ima odvisnosti (400)

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

Rešitev: Preden izbrišete izdajatelja, izbrišite vse značke, povezane z njim. Podobno izbrišite vse poverilnice pod značko, preden izbrišete značko.

Ni pooblastila (400)

{ "error": "not authorized" }

Napake pooblastil so napake pri preverjanju, zato vrnejo 400 (ne 401 ali 403).

Rešitev: Spreminjate lahko le vire, ki jih imate v lasti. Prepričajte se, da uporabljate pravilen ključ API.

HTML v besedilu za deljenje

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

Rešitev: Besedilo za deljenje mora biti navadno besedilo. Iz parametra text odstranite vse oznake HTML.