Saltar al contenido principal

¿Qué es una Página de Error Whitelabel? Una Guía Técnica Completa

spring-bootwhitelabel-error-pagejava-webAlrededor de 3 min

¿Qué es una Página de Error Whitelabel? Una Guía Técnica Completa

Al construir aplicaciones basadas en Java—especialmente con Spring Boot—los desarrolladores a veces se encuentran con una pantalla blanca simple titulada “Página de Error Whitelabel.”
A menudo aparece inesperadamente, generalmente en el peor momento posible, y plantea la misma pregunta cada vez: ¿Qué causó esto exactamente y cómo puedo evitar que vuelva a suceder?

Esta guía desglosa el significado de esta página de error, por qué aparece y cómo reemplazarla con un manejo de errores adecuado para entornos de producción.

¿Qué es exactamente una Página de Error Whitelabel?

Una Página de Error Whitelabel es la página HTML de respaldo de Spring Boot que aparece cuando la aplicación encuentra un problema pero no puede encontrar un controlador de errores personalizado.

En términos más simples:

Tu aplicación se rompió, pero Spring Boot no tenía una página de error personalizada para mostrar—por lo que utilizó su marcador de posición incorporado.

Este marcador de posición aparece tanto en rutas web típicas como en puntos finales REST si el backend cree que el cliente espera HTML.

Los desencadenantes comunes incluyen:

  • Mapeos de controlador faltantes
  • Excepciones lanzadas durante el manejo de solicitudes
  • Enrutamiento de solicitudes incorrecto
  • Motor de plantillas deshabilitado o faltante
  • No se define un controlador /error personalizado

Si bien la página en sí es inofensiva, no es ideal para aplicaciones o APIs del mundo real.

¿Por qué aparece esta Página de Error?

A continuación se presentan las causas subyacentes más frecuentes:

1. La URL solicitada no tiene un controlador coincidente

Un usuario accede a algo como:

/api/user/profile/get-more-info

pero solo implementaste rutas bajo /api/user.

Spring Boot responde con su página de error predeterminada.

2. La aplicación lanza una excepción no manejada

Por ejemplo:

  • NullPointerException
  • Fallo de validación
  • Errores de conectividad a la base de datos

Si no tienes un controlador de excepciones global, se sirve la página Whitelabel predeterminada.

3. La solicitud del cliente se interpreta como una solicitud de navegador

Los clientes REST deben especificar:

Accept: application/json

Si falta este encabezado, Spring Boot puede asumir que el cliente quiere HTML y devolver la página Whitelabel en lugar de JSON.

4. Dependencias web faltantes o incompletas

Si accidentalmente eliminas una dependencia como:

<artifactId>spring-boot-starter-web</artifactId>

La auto-configuración de Spring puede fallar, activando el comportamiento de respaldo.

5. Sin controlador de error personalizado o plantilla de error personalizada

Spring Boot verifica:

/error
/templates/error/
static/error/

Si no se encuentran → página de respaldo.

Cómo eliminar la Página de Error Whitelabel

Spring Boot permite varias soluciones limpias dependiendo de las necesidades de tu aplicación.

Solución 1: Desactivar la Página Whitelabel por Completo

Agrega esto a tu configuración:

server.error.whitelabel.enabled=false

Esto detendrá a Spring Boot de mostrar la página de respaldo.

Solución 2: Crea tus Propias Páginas de Error HTML

Para aplicaciones web, agrega archivos como:

src/main/resources/templates/error/404.html  
src/main/resources/templates/error/500.html

Spring Boot utiliza automáticamente estos archivos al coincidir con los códigos de estado.

Solución 3: Implementa un Controlador de Error Personalizado

Ideal para APIs backend que desean respuestas JSON limpias:

@RestController
public class CustomErrorController implements ErrorController {

    @RequestMapping("/error")
    public Map<String, Object> handleError(HttpServletResponse response) {
        Map<String, Object> data = new HashMap<>();
        data.put("status", response.getStatus());
        data.put("error", "La solicitud falló");
        return data;
    }
}

Esto asegura que todos los errores devuelvan JSON estructurado en lugar de HTML.

Solución 4: Agrega Manejo de Excepciones Global

Usando @RestControllerAdvice:

@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, Object>> handle(Exception ex) {
        Map<String, Object> error = new HashMap<>();
        error.put("message", ex.getMessage());
        error.put("code", 500);
        return ResponseEntity.status(500).body(error);
    }
}

Esto previene que las excepciones no manejadas caigan en la página predeterminada.

Solución 5: Asegúrate de que las Rutas del Frontend y del Backend No Colisionen

Las aplicaciones de una sola página (React, Vue, Angular) a menudo actualizan páginas que no existen en el backend. Configurar un respaldo adecuado o una regla de reescritura del servidor ayuda a evitar respuestas Whitelabel inesperadas.

Mejores Prácticas para Producción

Para evitar la página predeterminada de Spring Boot por completo, sigue estas pautas:

  • Siempre define páginas de error personalizadas para aplicaciones orientadas al usuario

  • Estandariza las respuestas de error JSON para APIs

  • Implementa manejo de excepciones global

  • Valida tus reglas de enrutamiento de solicitudes

  • Asegúrate de que tu frontend establezca los encabezados adecuados

  • Mantén un registro consistente para facilitar la depuración

Con estas prácticas, tus usuarios—y tus registros—nunca más estarán desordenados con sorpresas Whitelabel.

FAQ

  1. ¿Por qué obtengo una Página de Error Whitelabel al actualizar la página en una aplicación React/Vue?

Porque el navegador solicita una ruta que solo existe en el frontend, no en el backend. Configura una ruta de respaldo en el frontend o una regla de reescritura del servidor.

  1. ¿Cómo cambio las respuestas de error a JSON en lugar de HTML?

Desactiva Whitelabel, agrega un controlador de excepciones global y proporciona un punto final /error personalizado que devuelva JSON.

  1. ¿Puedo eliminar la Página de Error Whitelabel por completo?

Sí. Solo agrega:

server.error.whitelabel.enabled=false

y implementa tu propio controlador de errores o plantilla HTML.

  1. ¿Por qué mi API devuelve la página Whitelabel en lugar de un objeto de error?

Lo más probable es que la solicitud carezca de:

Accept: application/json

Spring Boot asume que el cliente quiere HTML.

  1. ¿Necesito una página separada para cada código de error?

No es necesario, pero se recomienda para sitios orientados al público. Para APIs, una estructura JSON unificada suele ser suficiente.

Pie de página predeterminado