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
402	Payment Required	Cuota mensual de otorgamientos alcanzada o la función requiere un plan superior
403	Forbidden	Límite del plan alcanzado (p. ej. tope de emisores o insignias)
404	Not Found	El recurso solicitado no existe
429	Too Many Requests	Límite de tasa superado
500	Internal Server Error	Se produjo un error inesperado en el servidor

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

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

Solución: Has usado todos los otorgamientos incluidos en tu plan para este periodo de facturación (Free: 100/mes, Starter: 1.000/mes, Pro: 10.000/mes). Espera al próximo reinicio o mejora tu plan. Consulta Planes y facturación.

Límite del plan alcanzado

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

Solución: Has alcanzado el tope de emisores, insignias o claves API de tu plan. Elimina un recurso que no uses o mejora tu plan.

Blockchain requiere Pro

{ "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 activar la verificación on-chain.

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

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

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

No autorizado

{ "error": "not authorized" }

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.