Błędy

Gdy żądanie do API kończy się niepowodzeniem, badges.ninja zwraca odpowiedź z błędem w formacie JSON wraz z odpowiednim kodem statusu 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	Nieprawidłowe żądanie	Brakujące lub nieprawidłowe parametry, osiągnięty limit planu lub przydział, funkcja wymaga wyższego planu albo brak autoryzacji — wszystkie błędy walidacji zwracają 400
402	Wymagana płatność	Zarezerwowany na wyczerpanie kredytów. API badges obecnie nie pobiera kredytów, więc w praktyce ten kod nigdy nie jest zwracany
404	Nie znaleziono	Żądany zasób nie istnieje
500	Wewnętrzny błąd serwera	Na serwerze wystąpił nieoczekiwany błąd

Nie ma kodów 403 ani 429: błędy autoryzacji zwracają 400 („not authorized”), a na poziomie aplikacji nie ma ograniczania liczby żądań.

Typowe błędy i rozwiązania

Brakujące wymagane parametry

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

Rozwiązanie: Uwzględnij w treści żądania wszystkie wymagane parametry. Pełną listę znajdziesz w dokumentacji danego endpointu.

Nieprawidłowy adres e-mail

{ "error": "invalid email" }

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

Nieprawidłowy adres URL

{ "error": "invalid URL" }

Rozwiązanie: Podaj pełny adres URL wraz z protokołem, np. https://example.com.

Zbyt krótka nazwa

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

Rozwiązanie: Użyj dłuższej nazwy. Nazwy wystawców muszą mieć co najmniej 3 znaki. Nazwy odbiorców muszą mieć co najmniej 5 znaków.

Wystawca niezweryfikowany

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

Rozwiązanie: Najpierw zweryfikuj wystawcę. Sprawdź, czy w skrzynce e-mail wystawcy jest link weryfikacyjny, lub skorzystaj z endpointu Weryfikacja wystawcy.

Osiągnięto limit poświadczeń (400)

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

Rozwiązanie: Wykorzystujesz pełną roczną pulę poświadczeń (Free: 1200/rok, Starter: 12 000/rok, Pro: 120 000/rok). Pula resetuje się w rocznicę rejestracji konta — nie na przełomie miesięcy kalendarzowych. Przejdź na wyższy plan, aby uzyskać większy limit. Zobacz Plany i rozliczenia.

Osiągnięto limit planu (400)

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

Limit odznak ma taką samą postać:

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

Rozwiązanie: Osiągnięto limit wystawców lub odznak w ramach planu. Usuń nieużywany zasób lub przejdź na wyższy plan.

Zasób ma powiązane elementy (400)

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

Rozwiązanie: Przed usunięciem wystawcy usuń wszystkie powiązane z nim odznaki. Podobnie przed usunięciem odznaki usuń wszystkie poświadczenia wystawione w jej ramach.

Brak autoryzacji (400)

{ "error": "not authorized" }

Błędy autoryzacji są błędami walidacji, dlatego zwracają 400 (a nie 401 ani 403).

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

HTML w tekście udostępniania

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

Rozwiązanie: Tekst udostępniania musi być zwykłym tekstem. Usuń wszystkie znaczniki HTML z parametru text.