Errores

Cuando una llamada a la API falla, badges.ninja devuelve una respuesta JSON de error con el código 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	Bad Request	Parámetros ausentes o inválidos
402	Payment Required	Bolsa mensual de otorgamientos agotada o función que requiere un plan superior
403	Forbidden	Límite de plan alcanzado (p. ej. tope de emisores o de credenciales)
404	Not Found	El recurso solicitado no existe
429	Too Many Requests	Límite de frecuencia superado
500	Internal Server Error	Ha ocurrido un error inesperado en el servidor

Errores frecuentes 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 inválido

{ "error": "invalid email" }

Solución: Proporciona un correo con formato válido como user@domain.com.

URL inválida

{ "error": "invalid URL" }

Solución: Proporciona una URL completa que incluya 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 caracteres.

Emisor no verificado

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

Solución: Verifica primero al emisor. Revisa su correo para el enlace de verificación, o utiliza el endpoint Verify Issuer.

Bolsa mensual agotada

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

Solución: Has agotado los otorgamientos que tu plan incluye para este periodo (Free: 100/mes, Starter: 1.000/mes, Pro: 10.000/mes). Espera al siguiente reinicio o sube de plan. Consulta Planes y facturación.

Límite de plan alcanzado

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

Solución: Has tocado el tope de emisores, credenciales o claves API de tu plan. Suprime algún recurso no usado o sube de plan.

Blockchain requiere Pro

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

Solución: El parámetro blockchain solo está disponible en el plan Pro. Sube de plan para activar la verificación on-chain.

Blockchain no compatible

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

Solución: De momento solo se admite matchain como valor del parámetro blockchain.

Recurso con dependencias

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

Solución: Suprime todas las credenciales del emisor antes de eliminarlo. De igual modo, suprime todos los otorgamientos de una credencial antes de suprimirla.

No autorizado

{ "error": "not authorized" }

Solución: Solo puedes modificar recursos que te pertenezcan. Asegúrate de estar usando la clave API correcta.

HTML en el texto de difusión

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

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