Fehler

Wenn eine API-Anfrage fehlschlägt, gibt badges.ninja eine JSON-Fehlerantwort mit einem passenden HTTP-Statuscode zurück.

Fehlerformat

Alle Fehler folgen dieser Struktur:

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

Statuscodes

Code	Bedeutung	Wann es auftritt
400	Bad Request	Fehlende oder ungültige Parameter, Plan-Limit oder Kontingent erreicht, Funktion erfordert einen höheren Plan oder fehlende Berechtigung — alle Validierungsfehler geben 400 zurück
402	Payment Required	Reserviert für erschöpfte Credits. Die Badges-API zieht derzeit keine Credits ab, daher wird dieser Code in der Praxis nie zurückgegeben
404	Not Found	Die angeforderte Ressource existiert nicht
500	Internal Server Error	Auf dem Server ist ein unerwarteter Fehler aufgetreten

Es gibt weder 403 noch 429: Autorisierungsfehler geben 400 („not authorized“) zurück, und es gibt kein Rate-Limiting auf Anwendungsebene.

Häufige Fehler und Lösungen

Fehlende Pflichtparameter

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

Lösung: Nimm alle Pflichtparameter in den Anfragetext auf. Die vollständige Liste findest du in der Dokumentation des jeweiligen Endpunkts.

Ungültige E-Mail-Adresse

{ "error": "invalid email" }

Lösung: Gib eine gültige E-Mail-Adresse im Format user@domain.com an.

Ungültige URL

{ "error": "invalid URL" }

Lösung: Gib eine vollständige URL inklusive Protokoll an, z. B. https://example.com.

Name zu kurz

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

Lösung: Verwende einen längeren Namen. Namen von Ausstellern benötigen mindestens 3 Zeichen. Namen von Empfänger:innen benötigen mindestens 5 Zeichen.

Aussteller nicht verifiziert

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

Lösung: Verifiziere zuerst den Aussteller. Suche in der E-Mail-Adresse des Ausstellers nach dem Verifizierungslink oder nutze den Endpunkt Aussteller verifizieren.

Nachweis-Kontingent erreicht (400)

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

Lösung: Du hast deinen gesamten jährlichen Nachweis-Pool aufgebraucht (Free: 1.200/Jahr, Starter: 12.000/Jahr, Pro: 120.000/Jahr). Der Pool wird am Jahrestag der Registrierung deines Kontos zurückgesetzt — nicht zum Monatswechsel. Wechsle zu einem höheren Plan, um mehr Kontingent zu erhalten. Siehe Pläne & Abrechnung.

Plan-Limit erreicht (400)

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

Das Limit für Abzeichen hat dieselbe Form:

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

Lösung: Du hast das Limit deines Plans für Aussteller oder Abzeichen erreicht. Lösche eine nicht benötigte Ressource oder wechsle zu einem höheren Plan.

Ressource hat Abhängigkeiten (400)

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

Lösung: Lösche alle mit dem Aussteller verknüpften Abzeichen, bevor du den Aussteller löschst. Entsprechend musst du alle Nachweise eines Abzeichens löschen, bevor du das Abzeichen löschst.

Nicht autorisiert (400)

{ "error": "not authorized" }

Autorisierungsfehler sind Validierungsfehler und geben daher 400 zurück (nicht 401 oder 403).

Lösung: Du kannst nur Ressourcen ändern, die dir gehören. Stelle sicher, dass du den richtigen API-Schlüssel verwendest.

HTML im Teilen-Text

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

Lösung: Der Teilen-Text muss reiner Text sein. Entferne alle HTML-Tags aus dem Parameter „text“.