Fouten

Wanneer een API-verzoek mislukt, geeft badges.ninja een JSON-foutrespons terug met een passende HTTP-statuscode.

Foutformaat

Alle fouten hebben deze structuur:

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

Statuscodes

Code	Betekenis	Wanneer het gebeurt
400	Bad Request	Ontbrekende of ongeldige parameters, planlimiet of quotum bereikt, functie vereist een hoger plan, of niet geautoriseerd — alle validatiefouten geven 400 terug
402	Payment Required	Gereserveerd voor uitgeputte credits. De badges-API trekt momenteel geen credits af, dus deze code wordt in de praktijk nooit teruggegeven
404	Not Found	De gevraagde resource bestaat niet
500	Internal Server Error	Er is een onverwachte fout opgetreden op de server

Er is geen 403 of 429: autorisatiefouten geven 400 terug ("not authorized") en er is geen rate limiting op applicatieniveau.

Veelvoorkomende fouten en oplossingen

Ontbrekende verplichte parameters

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

Oplossing: Neem alle verplichte parameters op in je request body. Raadpleeg de endpointdocumentatie voor de volledige lijst.

Ongeldig e-mailadres

{ "error": "invalid email" }

Oplossing: Geef een geldig e-mailadres op in het formaat user@domain.com.

Ongeldige URL

{ "error": "invalid URL" }

Oplossing: Geef een volledige URL op inclusief protocol, bijvoorbeeld https://example.com.

Naam te kort

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

Oplossing: Gebruik een langere naam. Namen van uitgevers moeten minimaal 3 tekens bevatten. Namen van ontvangers moeten minimaal 5 tekens bevatten.

Uitgever niet geverifieerd

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

Oplossing: Verifieer eerst de uitgever. Zoek de verificatielink in het e-mailadres van de uitgever, of gebruik het endpoint Verify Issuer.

Credentialquotum bereikt (400)

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

Oplossing: Je hebt je volledige jaarlijkse credentialpool opgebruikt (Free: 1.200/jaar, Starter: 12.000/jaar, Pro: 120.000/jaar). De pool wordt gereset op de verjaardag van de registratie van je account — niet bij de maandwisseling. Upgrade je plan voor een hoger quotum. Zie Plannen en facturering.

Planlimiet bereikt (400)

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

De limiet voor badges heeft dezelfde vorm:

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

Oplossing: Je hebt de limiet van je plan voor uitgevers of badges bereikt. Verwijder een ongebruikte resource of upgrade je plan.

Resource heeft afhankelijkheden (400)

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

Oplossing: Verwijder alle badges die aan de uitgever zijn gekoppeld voordat je de uitgever verwijdert. Verwijder op dezelfde manier alle credentials onder een badge voordat je de badge verwijdert.

Niet geautoriseerd (400)

{ "error": "not authorized" }

Autorisatiefouten zijn validatiefouten, dus ze geven 400 terug (niet 401 of 403).

Oplossing: Je kunt alleen resources wijzigen die van jou zijn. Zorg ervoor dat je de juiste API-sleutel gebruikt.

HTML in deeltekst

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

Oplossing: Deeltekst moet platte tekst zijn. Verwijder alle HTML-tags uit de tekstparameter.