Fehler

Wenn eine API-Anfrage fehlschlägt, liefert badges.ninja eine JSON-Fehlerantwort mit passendem HTTP-Statuscode.

Fehlerformat

Alle Fehler folgen dieser Struktur:

{
  "error": "Beschreibung, was schiefging"
}

Statuscodes

Code	Bedeutung	Wann das passiert
400	Bad Request	Fehlende oder ungültige Parameter
402	Payment Required	Monatliches Vergabekontingent erreicht oder Funktion erfordert einen höheren Plan
403	Forbidden	Plan-Limit erreicht (z. B. Aussteller- oder Auszeichnungs-Obergrenze)
404	Not Found	Die angeforderte Ressource existiert nicht
429	Too Many Requests	Ratenlimit überschritten
500	Internal Server Error	Unerwarteter Fehler auf dem Server

Häufige Fehler und Lösungen

Fehlende Pflichtparameter

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

Lösung: Füge alle Pflichtparameter in den Anfrage-Body ein. Die vollständige Liste findest du in der Endpunkt-Dokumentation.

Ungültige E-Mail

{ "error": "invalid email" }

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

Ungültige URL

{ "error": "invalid URL" }

Lösung: Verwende eine vollständige URL inkl. Protokoll, z. B. https://example.com.

Name zu kurz

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

Lösung: Nimm einen längeren Namen. Ausstellernamen benötigen mindestens 3 Zeichen, Empfängernamen mindestens 5.

Aussteller nicht verifiziert

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

Lösung: Verifiziere zuerst den Aussteller. Schau im E-Mail-Postfach des Ausstellers nach dem Verifizierungs-Link oder nutze den Endpunkt Aussteller verifizieren.

Monatliches Vergabekontingent erreicht

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

Lösung: Du hast alle Vergaben deines Plans für diese Abrechnungsperiode aufgebraucht (Free: 100/Monat, Starter: 1.000/Monat, Pro: 10.000/Monat). Warte auf die nächste Zurücksetzung oder führe ein Upgrade durch. Siehe Pläne & Abrechnung.

Plan-Limit erreicht

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

Lösung: Du hast das Plan-Limit für Aussteller, Auszeichnungen oder API-Schlüssel erreicht. Lösche eine ungenutzte Ressource oder führe ein Upgrade durch.

Blockchain erfordert Pro

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

Lösung: Der blockchain-Parameter ist nur im Pro-Plan verfügbar. Aktualisiere auf Pro, um On-Chain-Verifizierung zu aktivieren.

Nicht unterstützte Blockchain

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

Lösung: Derzeit ist nur matchain als Blockchain-Parameter unterstützt.

Ressource mit Abhängigkeiten

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

Lösung: Lösche alle Auszeichnungen unter einem Aussteller, bevor du den Aussteller löschst. Ebenso alle Vergaben unter einer Auszeichnung, bevor du sie löschst.

Nicht autorisiert

{ "error": "not authorized" }

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

HTML im Share-Text

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

Lösung: Der Share-Text muss Klartext sein. Entferne alle HTML-Tags aus dem Text-Parameter.