Errores

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

Formato de error

Todos los errores siguen esta estructura:

{
  "error": "descripción de lo que ha fallado"
}

Códigos de estado

Código	Significado	Cuándo ocurre
400	Bad Request	Parámetros faltantes o inválidos, límite del plan o cuota alcanzada, la función requiere un plan superior, o no autorizado — todos los fallos de validación devuelven 400
402	Payment Required	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	Not Found	El recurso solicitado no existe
500	Internal Server Error	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

Parámetros requeridos ausentes

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

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

Correo inválido

{ "error": "invalid email" }

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

URL inválida

{ "error": "invalid URL" }

Solución: Usa una URL completa incluyendo el protocolo, p. ej. 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.

Emisor no verificado

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

Solución: Verifica primero el emisor. Revisa el correo del emisor para el enlace de verificación, o usa el endpoint Verificar emisor.

Cuota mensual de otorgamientos alcanzada (400)

{ "error": "monthly award quota reached (100/100 on the free plan) — wait for the 1st of next month or upgrade your plan" }

Solución: Has usado todos los otorgamientos incluidos en tu plan para el mes natural en curso (Free: 100/mes, Starter: 1.000/mes, Pro: 10.000/mes). El contador se reinicia a las 00:00 UTC del día 1 de cada mes; mejora tu plan para obtener un límite mayor. Consulta Planes y facturación.

Límite del plan alcanzado (400)

{ "error": "issuer limit reached (1/1 on the free plan) — delete an issuer or upgrade your plan" }

El tope 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 tope de emisores o insignias de tu plan. Elimina un recurso que no uses o mejora tu plan.

Blockchain requiere Pro (400)

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

Solución: El parámetro blockchain solo está disponible en el plan Pro. Pásate a Pro para activarlo.

Blockchain no soportada

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

Solución: Actualmente solo se admite matchain como parámetro de blockchain.

Recurso con dependencias (400)

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

Solución: Elimina todas las insignias vinculadas al emisor antes de borrar el emisor. Del mismo modo, elimina todos los otorgamientos de una insignia antes de borrarla.

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 recursos que te pertenezcan. Asegúrate de usar la clave API correcta.

HTML en el texto de compartición

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

Solución: El texto de compartición debe ser texto plano. Elimina cualquier etiqueta HTML del parámetro de texto.