Erreurs

Lorsqu'une requête API échoue, badges.ninja renvoie une réponse d'erreur JSON accompagnée d'un code de statut HTTP approprié.

Format d'erreur

Toutes les erreurs suivent cette structure :

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

Codes de statut

Code	Signification	Quand cela se produit
400	Bad Request	Paramètres manquants ou invalides, limite de plan ou quota atteint, fonctionnalité nécessitant un plan supérieur, ou accès non autorisé — tous les échecs de validation renvoient 400
402	Payment Required	Réservé à l'épuisement des crédits. L'API badges ne déduit actuellement aucun crédit, ce code n'est donc jamais renvoyé en pratique
404	Not Found	La ressource demandée n'existe pas
500	Internal Server Error	Une erreur inattendue s'est produite sur le serveur

Il n'y a ni 403 ni 429 : les échecs d'autorisation renvoient 400 (« not authorized ») et il n'existe aucune limitation de débit au niveau applicatif.

Erreurs courantes et solutions

Paramètres obligatoires manquants

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

Solution : incluez tous les paramètres obligatoires dans le corps de votre requête. Consultez la documentation du point de terminaison pour la liste complète.

E-mail invalide

{ "error": "invalid email" }

Solution : indiquez une adresse e-mail valide au format user@domain.com.

URL invalide

{ "error": "invalid URL" }

Solution : indiquez une URL complète, protocole inclus, par exemple https://example.com.

Nom trop court

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

Solution : utilisez un nom plus long. Les noms d'émetteur doivent comporter au moins 3 caractères. Les noms de destinataire doivent comporter au moins 5 caractères.

Émetteur non vérifié

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

Solution : vérifiez d'abord l'émetteur. Consultez l'e-mail de l'émetteur pour trouver le lien de vérification, ou utilisez le point de terminaison Vérifier l'émetteur.

Quota de crédentiels atteint (400)

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

Solution : vous avez utilisé la totalité de votre réserve annuelle de crédentiels (Free : 1 200/an, Starter : 12 000/an, Pro : 120 000/an). La réserve est réinitialisée à la date anniversaire de l'inscription de votre compte, et non au changement de mois civil. Passez à un plan supérieur pour obtenir une allocation plus importante. Voir Plans et facturation.

Limite du plan atteinte (400)

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

La limite de badges suit le même format :

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

Solution : vous avez atteint le plafond de votre plan pour les émetteurs ou les badges. Supprimez une ressource inutilisée ou passez à un plan supérieur.

La ressource a des dépendances (400)

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

Solution : supprimez tous les badges liés à l'émetteur avant de supprimer celui-ci. De même, supprimez tous les crédentiels d'un badge avant de supprimer ce badge.

Non autorisé (400)

{ "error": "not authorized" }

Les échecs d'autorisation sont des erreurs de validation : ils renvoient donc 400 (et non 401 ou 403).

Solution : vous ne pouvez modifier que les ressources dont vous êtes propriétaire. Assurez-vous d'utiliser la bonne clé API.

HTML dans le texte de partage

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

Solution : le texte de partage doit être du texte brut. Supprimez toutes les balises HTML du paramètre text.