Błędy

Gdy żądanie API kończy się niepowodzeniem, badges.ninja zwraca odpowiedź JSON z błędem oraz odpowiedni kod HTTP.

Format błędu

Wszystkie błędy mają następującą strukturę:

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

Kody statusu

Kod	Znaczenie	Kiedy występuje
400	Bad Request	Brakujące lub nieprawidłowe parametry
402	Payment Required	Osiągnięty miesięczny limit wydań lub funkcja wymaga wyższego planu
403	Forbidden	Osiągnięty limit planu (np. liczba wystawców lub odznak)
404	Not Found	Żądany zasób nie istnieje
429	Too Many Requests	Przekroczony limit szybkości
500	Internal Server Error	Nieoczekiwany błąd po stronie serwera

Typowe błędy i rozwiązania

Brakujące wymagane parametry

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

Rozwiązanie: Dołącz wszystkie wymagane parametry w treści żądania. Sprawdź dokumentację endpointu, aby zobaczyć pełną listę.

Nieprawidłowy e-mail

{ "error": "invalid email" }

Rozwiązanie: Podaj prawidłowy adres e-mail w formacie user@domain.com.

Nieprawidłowy URL

{ "error": "invalid URL" }

Rozwiązanie: Podaj pełny URL zawierający protokół, np. https://example.com.

Za krótka nazwa

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

Rozwiązanie: Użyj dłuższej nazwy. Nazwy wystawców wymagają co najmniej 3 znaków. Imiona odbiorców wymagają co najmniej 5 znaków.

Wystawca niezweryfikowany

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

Rozwiązanie: Najpierw zweryfikuj wystawcę. Sprawdź e-mail wystawcy w poszukiwaniu linku weryfikacyjnego lub użyj endpointu Weryfikuj wystawcę.

Osiągnięty miesięczny limit wydań

{ "error": "monthly award quota reached" }

Rozwiązanie: Wykorzystałeś wszystkie wydania zawarte w swoim planie na ten okres rozliczeniowy (Free: 100/mies, Starter: 1 000/mies, Pro: 10 000/mies). Poczekaj na następny reset lub zmień plan. Zobacz Plany i rozliczenia.

Osiągnięty limit planu

{ "error": "issuer limit reached for your plan" }

Rozwiązanie: Osiągnąłeś limit planu na wystawców, odznaki lub klucze API. Usuń nieużywany zasób lub zmień plan.

Blockchain wymaga planu Pro

{ "error": "blockchain verification requires the Pro plan" }

Rozwiązanie: Parametr blockchain dostępny jest tylko w planie Pro. Przejdź na Pro, aby włączyć weryfikację on-chain.

Nieobsługiwany blockchain

{ "error": "unsupported blockchain, only 'matchain' is supported" }

Rozwiązanie: Obecnie tylko matchain jest obsługiwany jako parametr blockchain.

Zasób ma zależności

{ "error": "issuer has badges and cannot be deleted" }

Rozwiązanie: Usuń wszystkie odznaki pod wystawcą przed usunięciem wystawcy. Podobnie usuń wszystkie wydania pod odznaką przed usunięciem odznaki.

Brak autoryzacji

{ "error": "not authorized" }

Rozwiązanie: Możesz modyfikować tylko zasoby, które posiadasz. Upewnij się, że używasz właściwego klucza API.

HTML w tekście udostępnienia

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

Rozwiązanie: Tekst udostępnienia musi być zwykłym tekstem. Usuń wszelkie tagi HTML z parametru text.