Errores

Cuando una solicitud a la API falla, badges.ninja devuelve una respuesta de error en JSON con el código de estado HTTP correspondiente.

Formato de error

Todos los errores siguen esta estructura:

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

Códigos de estado

Código	Significado	Cuándo ocurre
400	Solicitud incorrecta	Parámetros ausentes o inválidos, límite del plan o cuota alcanzados, función que requiere un plan superior o falta de autorización: todos los fallos de validación devuelven 400
402	Pago requerido	Reservado para el agotamiento de créditos. La API de badges no descuenta créditos actualmente, por lo que este código nunca se devuelve en la práctica
404	No encontrado	El recurso solicitado no existe
500	Error interno del servidor	Se produjo un error inesperado en el servidor

No existe 403 ni 429: los fallos de autorización devuelven 400 ("not authorized") y no hay limitación de tasa a nivel de aplicación.

Errores comunes y soluciones

Faltan parámetros obligatorios

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

Solución: Incluye todos los parámetros obligatorios en el cuerpo de la solicitud. Consulta la documentación del endpoint para ver la lista completa.

Correo electrónico no válido

{ "error": "invalid email" }

Solución: Proporciona una dirección de correo electrónico válida con el formato user@domain.com.

URL no válida

{ "error": "invalid URL" }

Solución: Proporciona una URL completa que incluya el protocolo, por ejemplo https://example.com.

Nombre demasiado corto

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

Solución: Usa un nombre más largo. Los nombres de emisor requieren al menos 3 caracteres. Los nombres de destinatario requieren al menos 5 caracteres.

Emisor no verificado

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

Solución: Verifica primero el emisor. Busca el enlace de verificación en el correo del emisor o usa el endpoint Verificar emisor.

Cuota de credenciales alcanzada (400)

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

Solución: Has usado todo tu fondo anual de credenciales (Free: 1.200/año, Starter: 12.000/año, Pro: 120.000/año). El fondo se restablece en el aniversario del registro de tu cuenta, no al cambiar de mes natural. Mejora tu plan para obtener una asignación mayor. Consulta Planes y facturación.

Límite del plan alcanzado (400)

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

El límite de insignias usa la misma forma:

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

Solución: Has alcanzado el límite de tu plan para emisores o insignias. Elimina un recurso que no uses o mejora tu plan.

El recurso tiene dependencias (400)

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

Solución: Elimina todas las insignias vinculadas al emisor antes de eliminarlo. Del mismo modo, elimina todas las credenciales de una insignia antes de eliminar la insignia.

No autorizado (400)

{ "error": "not authorized" }

Los fallos de autorización son errores de validación, por lo que devuelven 400 (no 401 ni 403).

Solución: Solo puedes modificar los recursos que te pertenecen. Asegúrate de usar la clave de API correcta.

HTML en el texto para compartir

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

Solución: El texto para compartir debe ser texto plano. Elimina cualquier etiqueta HTML del parámetro text.