Errors

Quan una sol·licitud a l'API falla, badges.ninja retorna una resposta d'error en JSON amb el codi d'estat HTTP corresponent.

Format dels errors

Tots els errors segueixen aquesta estructura:

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

Codis d'estat

Codi	Significat	Quan passa
400	Bad Request	Paràmetres absents o no vàlids, límit del pla o quota assolits, la funcionalitat requereix un pla superior o no autoritzat — totes les fallades de validació retornen 400
402	Payment Required	Reservat per a l'esgotament de crèdits. L'API d'insígnies actualment no dedueix crèdits, de manera que aquest codi mai no es retorna a la pràctica
404	Not Found	El recurs sol·licitat no existeix
500	Internal Server Error	S'ha produït un error inesperat al servidor

No hi ha 403 ni 429: les fallades d'autorització retornen 400 ("not authorized") i no hi ha limitació de velocitat a la capa d'aplicació.

Errors habituals i solucions

Falten paràmetres obligatoris

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

Solució: Inclou tots els paràmetres obligatoris al cos de la sol·licitud. Consulta la documentació de l'endpoint per veure la llista completa.

Correu electrònic no vàlid

{ "error": "invalid email" }

Solució: Indica una adreça de correu vàlida amb el format user@domain.com.

URL no vàlid

{ "error": "invalid URL" }

Solució: Indica un URL complet que inclogui el protocol, per exemple https://example.com.

Nom massa curt

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

Solució: Utilitza un nom més llarg. Els noms d'emissor requereixen almenys 3 caràcters. Els noms de destinatari requereixen almenys 5 caràcters.

Emissor no verificat

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

Solució: Verifica primer l'emissor. Revisa el correu de l'emissor per trobar l'enllaç de verificació, o utilitza l'endpoint Verificar un emissor.

Quota de credencials assolida (400)

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

Solució: Has fet servir tot el teu fons anual de credencials (Free: 1.200/any, Starter: 12.000/any, Pro: 120.000/any). El fons es restableix en l'aniversari del registre del teu compte — no en el canvi de mes natural. Millora el teu pla per obtenir una assignació més gran. Consulta Plans i facturació.

Límit del pla assolit (400)

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

El límit d'insígnies té la mateixa forma:

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

Solució: Has assolit el límit del teu pla d'emissors o d'insígnies. Elimina un recurs que no utilitzis o millora el teu pla.

El recurs té dependències (400)

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

Solució: Elimina totes les insígnies vinculades a l'emissor abans d'eliminar-lo. De la mateixa manera, elimina totes les credencials d'una insígnia abans d'eliminar la insígnia.

No autoritzat (400)

{ "error": "not authorized" }

Les fallades d'autorització són errors de validació, per això retornen 400 (no 401 ni 403).

Solució: Només pots modificar recursos dels quals ets propietari. Assegura't que fas servir la clau d'API correcta.

HTML al text per compartir

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

Solució: El text per compartir ha de ser text pla. Elimina qualsevol etiqueta HTML del paràmetre text.