Erreurs

Quand une requête API échoue, badges.ninja renvoie une réponse d'erreur JSON avec le code HTTP approprié.

Format d'erreur

Toutes les erreurs suivent cette structure :

{
  "error": "description de ce qui a échoué"
}

Codes de statut

Code	Signification	Quand cela arrive
400	Bad Request	Paramètres manquants ou invalides
402	Payment Required	Quota mensuel d'attributions atteint ou fonctionnalité nécessitant un forfait supérieur
403	Forbidden	Limite de forfait atteinte (par ex. plafond d'émetteurs ou badges)
404	Not Found	La ressource demandée n'existe pas
429	Too Many Requests	Limite de débit dépassée
500	Internal Server Error	Erreur inattendue côté serveur

Erreurs courantes et solutions

Paramètres requis manquants

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

Solution : Incluez tous les paramètres requis dans le corps de la requête. Consultez la documentation de l'endpoint pour la liste complète.

E-mail invalide

{ "error": "invalid email" }

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

URL invalide

{ "error": "invalid URL" }

Solution : Fournissez une URL complète avec le protocole, par ex. https://example.com.

Nom trop court

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

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

Émetteur non vérifié

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

Solution : Vérifiez d'abord l'émetteur. Consultez la boîte mail de l'émetteur pour le lien de vérification, ou utilisez l'endpoint Vérifier l'émetteur.

Quota mensuel d'attributions atteint

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

Solution : Vous avez utilisé toutes les attributions incluses dans votre forfait pour cette période de facturation (Free : 100/mois, Starter : 1 000/mois, Pro : 10 000/mois). Attendez la prochaine réinitialisation ou mettez à niveau votre forfait. Voir Forfaits et facturation.

Limite de forfait atteinte

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

Solution : Vous avez atteint le plafond de votre forfait pour les émetteurs, badges ou clés API. Supprimez une ressource inutilisée ou mettez à niveau votre forfait.

Blockchain nécessite Pro

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

Solution : Le paramètre blockchain n'est disponible que sur le forfait Pro. Passez à Pro pour activer la vérification on-chain.

Blockchain non prise en charge

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

Solution : Actuellement, seul matchain est pris en charge comme paramètre de blockchain.

Ressource avec dépendances

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

Solution : Supprimez tous les badges sous l'émetteur avant de le supprimer. De même, supprimez toutes les attributions d'un badge avant de supprimer le badge.

Non autorisé

{ "error": "not authorized" }

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 toute balise HTML du paramètre de texte.