Plantilla de Página de Estado de API para Incidentes

Resumen

Una página de estado pública les dice a los consumidores de tu API qué está pasando antes de que abran un ticket de soporte. Reduce las solicitudes entrantes durante caídas y genera confianza a través de transparencia. Esta plantilla cubre la estructura, contenido y prácticas operacionales para mantener una página de estado que realmente ayude.

La plantilla cubre:

1. Estructura de página — qué secciones incluir y cómo organizarlas
2. Comunicación de incidentes — plantillas para incidentes activos y actualizaciones post-incidente
3. Definiciones de severidad — niveles estandarizados para que los consumidores entiendan el impacto
4. Reporte de SLA — cómo presentar métricas de uptime y tiempo de respuesta
5. Ventanas de mantenimiento — cómo programar y comunicar downtime planificado

Cuándo Usar

Usa esta plantilla cuando:

• Corres una API orientada a clientes y los consumidores abren tickets durante las caídas
• Estás montando una API pública nueva y quieres la página de estado lista antes del lanzamiento
• Tu equipo publica updates de incidentes ad hoc y el tono deriva cada vez

Sáltala cuando: el servicio es interno de un solo equipo — un canal de Slack con alertas automatizadas lo cubre, y una página pública anuncia una disponibilidad que nunca prometiste. Para el trabajo de resiliencia y no la capa de comunicación, consulta la plantilla de comunicación de incidentes.

Plantilla de Estructura de Página

<!-- Layout de Página de Estado -->
<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Estado de [Producto]</title>
    <!-- Debe estar en un dominio/infraestructura separada -->
</head>
<body>
    <header>
        <h1>Estado de [Producto]</h1>
        <p>Estado en tiempo real de los servicios y APIs de [Producto].</p>
        <!-- Botones de suscripción: Email, RSS, Slack, Webhook -->
        <nav>
            <a href="#current">Estado Actual</a>
            <a href="#history">Historial de Incidentes</a>
            <a href="#uptime">Métricas de Uptime</a>
            <a href="#maintenance">Mantenimiento Programado</a>
        </nav>
    </header>

    <main>
        <!-- Sección de Estado Actual -->
        <section id="current">
            <h2>Estado Actual</h2>
            <!-- Banner de estado general -->
            <div class="status-banner operational">
                Todos los sistemas operacionales
            </div>
            <!-- Estado por servicio -->
            <div class="service-list">
                <div class="service">
                    <span class="name">API Gateway</span>
                    <span class="status operational">Operacional</span>
                </div>
                <div class="service">
                    <span class="name">Servicio de Autenticación</span>
                    <span class="status operational">Operacional</span>
                </div>
                <div class="service">
                    <span class="name">Base de Datos (Primaria)</span>
                    <span class="status operational">Operacional</span>
                </div>
                <div class="service">
                    <span class="name">Dashboard Web</span>
                    <span class="status operational">Operacional</span>
                </div>
            </div>
        </section>

        <!-- Sección de Métricas de Uptime -->
        <section id="uptime">
            <h2>Uptime (90 días)</h2>
            <div class="uptime-grid">
                <!-- 90 barras diarias, coloreadas por estado -->
                <div class="uptime-bar operational" title="2026-07-04: 100% uptime"></div>
                <div class="uptime-bar operational" title="2026-07-03: 100% uptime"></div>
                <div class="uptime-bar degraded" title="2026-07-02: 99.2% uptime"></div>
                <!-- ... 87 barras más ... -->
            </div>
            <table class="uptime-table">
                <tr><th>Servicio</th><th>Uptime 90 días</th><th>SLA objetivo</th></tr>
                <tr><td>API Gateway</td><td>99.98%</td><td>99.9%</td></tr>
                <tr><td>Autenticación</td><td>99.99%</td><td>99.95%</td></tr>
                <tr><td>Base de Datos</td><td>99.97%</td><td>99.9%</td></tr>
            </table>
        </section>

        <!-- Sección de Historial de Incidentes -->
        <section id="history">
            <h2>Historial de Incidentes</h2>
            <article class="incident resolved">
                <h3>Pico de latencia en base de datos</h3>
                <p class="date">2 de Julio, 2026 — Resuelto</p>
                <p class="severity">Severidad: Media</p>
                <div class="updates">
                    <div class="update">
                        <time>14:32 UTC</time>
                        <p>Investigando latencia elevada en base de datos del cluster primario.</p>
                    </div>
                    <div class="update">
                        <time>14:45 UTC</time>
                        <p>Causa identificada: query analítica de larga duración bloqueando escrituras.</p>
                    </div>
                    <div class="update">
                        <time>15:10 UTC</time>
                        <p>Terminada la query bloqueante. Latencia volviendo a la normalidad.</p>
                    </div>
                    <div class="update">
                        <time>15:30 UTC</time>
                        <p>Resuelto. Latencia de vuelta al baseline. Agregando timeout de query para prevenir recurrencia.</p>
                    </div>
                </div>
            </article>
        </section>

        <!-- Sección de Mantenimiento Programado -->
        <section id="maintenance">
            <h2>Mantenimiento Programado</h2>
            <article class="maintenance upcoming">
                <h3>Migración de base de datos a v16</h3>
                <p class="date">15 de Julio, 2026, 02:00–04:00 UTC</p>
                <p>Impacto: Errores breves de API durante failover (esperado < 2 minutos).</p>
                <p>Haremos failover a la réplica, upgrade del primario, luego failback.</p>
            </article>
        </section>
    </main>
</body>
</html>

Plantillas de Actualización de Incidentes

Incidente activo — post inicial

## [Título del Incidente]

**Severidad:** [Crítica / Alta / Media / Baja]
**Inicio:** [timestamp UTC]
**Servicios afectados:** [lista]

Estamos investigando [descripción breve]. [Lo que experimentan los usuarios].

Próxima actualización: [hora, típicamente 15-30 minutos].

Resumen post-incidente

## [Título del Incidente] — Resumen

**Estado:** Resuelto
**Duración:** [inicio] – [fin] UTC ([N minutos])
**Severidad:** [nivel]

**Qué pasó:** [2-3 frases, lenguaje claro, sin jerga]

**Qué experimentaron los usuarios:** [tasas de error, endpoints afectados, features degradadas]

**Causa raíz:** [un párrafo — qué se rompió realmente]

**Qué hacemos para prevenir la recurrencia:**
- [ ] [acción + responsable + fecha]
- [ ] [acción + responsable + fecha]

Postmortem completo: [link]

Definiciones de Severidad

Severidad	Significado	Impacto en usuarios	Tiempo de respuesta	Frecuencia de update
Crítica	Caída mayor	Servicio no disponible o pérdida de datos para todos	Inmediato	Cada 15 minutos
Alta	Degradación significativa	Feature principal roto o muy lento para muchos	< 15 minutos	Cada 30 minutos
Media	Degradación parcial	Feature no crítico lento o no disponible, workaround existe	< 1 hora	Cada 1 hora
Baja	Issue menor	Problema cosmético o edge-case, impacto mínimo	< 4 horas	Al resolver

Definiciones de SLA

Métrica	Objetivo	Ventana de medición
Uptime	99.9%	30 días móviles
Tiempo de respuesta p95	< 500 ms	7 días móviles
MTTA de incidentes	< 5 min	Por incidente
Cadencia de updates	Cada 15-30 min durante incidentes	Por incidente

Operando la Página Durante un Incidente

La página de estado falla siempre en el mismo sitio: nadie es dueño de ella en pleno incidente. Antes del lanzamiento, decide quién escribe los updates (normalmente el incident commander o su adjunto, no el ingeniero que arregla el problema), quién los aprueba (una persona, no un comité — la velocidad gana al pulido) y dónde viven los borradores (un doc compartido gana a un hilo de Slack que se desplaza). Corre el flujo completo en un drill una vez por trimestre; la primera vez que un equipo aprende la cadencia de updates no debería ser durante una caída real.

Un patrón interno útil es el canal de estado sombra: un canal privado donde el on-call publica hallazgos crudos y el comunicador designado los traduce a updates para el consumidor. Mantiene la página pública honesta sin filtrar el caos interno.

Comunicación Multi-Canal

La página de estado es la fuente canónica, pero nadie refresca una página durante su propia caída. Empuja el mismo update a cada canal de suscripción — email, RSS, webhook de Slack — y mantén la redacción idéntica. Un suscriptor que recibe una severidad distinta en Slack que en la página asume que la página está desactualizada. Para consumidores con integraciones estrictas, un feed RSS o un endpoint /status.json (ofrecido por Statuspage.io y la mayoría de herramientas self-hosted) permite a su monitoreo leer el estado programáticamente en vez de raspar HTML.

Midiendo si Funciona

Tres números dicen si la página se gana su lugar: deflexión de tickets durante incidentes (volumen de soporte en días de caída contra la línea base — una buena página lo reduce notablemente), crecimiento de suscriptores (suscripciones estancadas significan que los consumidores no saben que la página existe; enlázala desde la doc de la API, el dashboard de desarrollador y los cuerpos de error 429/5xx), y tiempo-hasta-primer-update (qué tan rápido cae el primer post público tras la detección — menos de 15 minutos es la barra que genera confianza).

Cómo Adaptar la Plantilla

Recorta el HTML a lo que tus consumidores realmente leen. Una API de cinco servicios no necesita nueve filas en la lista — nombra los servicios que los consumidores mencionan en tickets, no los que tiene tu diagrama de arquitectura. Quita la grilla de uptime si todavía no la calculas con datos reales; una métrica ausente se ve mejor que un número inventado. Conserva el historial de incidentes y los botones de suscripción pase lo que pase — esas dos secciones son la razón de existir de la página. Para configuraciones multi-región, agrupa servicios por región y deja que cada región lleve su propio banner, para que una caída en EU no grite “caído” a los consumidores de EE.UU.

Ejemplo de Incidente Resuelto

Observa cómo un incidente real se mueve por la página — vuelve la plantilla concreta. 14:02 UTC: el monitoreo dispara por tasas elevadas de 5xx en el endpoint de pagos. 14:07: el incident commander publica el primer update, severidad Alta — “Investigando tasas de error elevadas en POST /payments. Próxima actualización 14:30 UTC.” Los consumidores que refrescan ven el banner cambiar a degradado a los minutos de la primera llamada fallida, no después de un ticket de soporte.

14:25: el equipo confirma un deploy malo como causa. Sale el segundo update — ahora con causa raíz, alcance afectado y ETA del rollback. Este es el update que compra buena voluntad: dice qué se rompió, a quién afecta y cuándo llega la próxima respuesta. 14:40: rollback verificado, métricas recuperándose; el tercer update marca “Monitoreando” — el resuelto se retiene hasta que las tasas de error se mantengan en baseline por diez minutos, según la lista de errores comunes. 14:55: banner de resuelto, lista de servicios en verde y una promesa — “Postmortem dentro de 48 horas.”

48 horas después, el resumen post-incidente reemplaza la promesa con links: qué pasó, causa raíz, las dos acciones con responsables. El incidente pasa al historial, donde genera confianza retroactivamente — un consumidor evaluando tu API el próximo trimestre leerá exactamente esa entrada y verá un relato honesto en vez de una página vacía que finge que las caídas nunca ocurren.

Comunicando Incumplimientos de SLA

Cuando un incidente cruza el umbral del SLA, la página de estado se convierte en un documento casi legal. Publica el reconocimiento del incumplimiento el mismo día — los consumidores enterprise calculan el uptime por sí mismos y un incumplimiento no reconocido se lee como ocultación. Indica el impacto medido (downtime en minutos, porcentaje de requests fallidas), la consecuencia contractual (créditos de servicio según la sección del SLA, cómo reclamarlos) y el camino de prevención. Los créditos son baratos comparados con el costo de confianza de hacer que los clientes te saquen los números.

Mantén una tabla fija de “uptime por mes” en la propia página — publicar un mes que quedó por debajo del objetivo, visiblemente, señala más confianza que cualquier disculpa. La página de Stripe muestra los números incluso cuando son malos; por eso la suya es la referencia.

Checklist de Lanzamiento

Antes de que la página salga en vivo, recorrela una vez de punta a punta:

• Hospedada en infraestructura separada — un subdominio status. en DNS distinta y un proveedor diferente al de la API
• Los estados por servicio se alimentan del monitoreo real, no de un toggle manual
• Al menos dos canales de suscripción conectados (email + RSS como mínimo)
• Tabla de severidad publicada y acordada con soporte — ellos responderán preguntas con ella
• El primer update de incidente llega a la página en menos de 15 minutos en un drill
• Plantilla de postmortem lista y el destino del link existe
• La propia página tiene su canal de fallback documentado
• Alguien queda nombrado como autor de updates para el próximo incidente

Los ítems sin marcar al lanzar se convierten en improvisación en pleno incidente — justo el momento en que la improvisación más duele.

Manteniendo la Página Honesta con el Tiempo

Las páginas de estado se pudren en silencio. Los servicios cambian de nombre mientras la página conserva los viejos, un servicio se retira pero su fila sigue en verde por meses, y las barras de uptime siguen dibujándose sobre una base de datos que ya nadie llama. La deriva es invisible porque nada falla — la página simplemente deja de describir el sistema que dice describir. Ponla en la misma cadencia de revisión que el diagrama de arquitectura que refleja: cuando un servicio nace, muere o cambia de nombre, la lista de estados cambia en el mismo PR o el mismo sprint.

Dos hábitos la mantienen creíble. Primero, enlaza cada incidente resuelto a su postmortem, y hazlo mientras el incidente está fresco — una promesa de publicar que no se cumple es peor que ninguna promesa. Segundo, prueba el camino aburrido cada trimestre: publica una ventana de mantenimiento falsa en staging, verifica que aparece en email, RSS y Slack, y luego quítala. Los canales que nunca ejercitas son los que fallan durante la caída real. Una página de estado es infraestructura que solo genera confianza mientras se mantiene aburrida y verdadera — el día que miente, cuesta más que no tener página.

Una Palabra sobre el Tono

La parte más difícil de la página no es el HTML — es la redacción durante un incidente en vivo. Mantén los updates en lenguaje claro: indica qué está roto, a quién afecta y cuándo llega el próximo update, en ese orden. Evita jerga interna (“la cola del worker de pagos está acumulándose”) a favor del impacto visible para el consumidor (“las requests de pago fallan o van lentas”). Di “nosotros” y no “el sistema” — rendir cuentas se lee como competencia. Y nunca especules sobre la causa en un update temprano; “hemos identificado un problema de conectividad de base de datos” está bien, “creemos que el proveedor está teniendo problemas” te lo citarán si resulta equivocado. La estructura de updates de la plantilla existe justamente para mantener esa disciplina bajo presión.

Esa disciplina también aplica en los períodos tranquilos: una página que solo despierta durante caídas entrena a los consumidores a consultarla solo después de que algo se rompe. Publica las ventanas de mantenimiento, los resúmenes de incidentes resueltos y la tabla de uptime aunque nada esté en llamas — la regularidad aburrida es lo que vuelve creíble el update alarmante cuando por fin llega.

Lo que funciona

• Actualiza cada 15-30 minutos durante incidentes activos — El silencio hace que los consumidores asuman lo peor
• Publica mantenimientos programados con 7 días de anticipación — Da tiempo a los consumidores para preparar alternativas
• Usa un dominio separado — status.example.com no debe depender de la API que monitorea. Consulta Circuit Breaker para patrones de resiliencia.
• Ofrece suscripciones RSS / email / Slack — Permite que los consumidores elijan cómo recibir actualizaciones
• Muestra uptime histórico — Un gráfico de 30 o 90 días genera confianza
• Sé honesto sobre rendimiento degradado — No marques un servicio como “operacional” cuando la latencia es 10x la normal. Consulta Performance Optimization para métricas de monitoreo.
• Enlaza a postmortems de incidentes — La transparencia después de la resolución genera confianza a largo plazo
• Define niveles de severidad públicamente — Los consumidores necesitan entender qué significa “severidad alta” para su integración
• Incluye estado por servicio, no solo general — Un banner único de “todo operacional” oculta degradaciones parciales
• Timestamp en cada actualización en UTC — Los consumidores en distintas timezones necesitan una referencia consistente

Errores Comunes

• Usar la misma infraestructura que la API para la página de estado — si la API cae, la página de estado también
• Marcar incidentes como resueltos demasiado pronto — espera hasta que las métricas confirmen recuperación por al menos 10 minutos
• Borrar o editar el historial de incidentes resueltos — los consumidores necesitan referenciar incidentes pasados
• Actualizaciones vagas como “estamos investigando” — comparte lo que sabes y lo que no sabes
• No definir niveles de severidad — los consumidores no pueden evaluar el impacto sin definiciones claras
• Esperar que nadie note — los consumidores monitorean tu API con sus propios checks; lo sabrán
• Olvidar postear el link del postmortem después de la resolución — el follow-through importa
• No testear la página de estado durante drills — si nunca la usaste bajo presión, fallará cuando la necesites

Variantes

Páginas de estado hospedadas (Statuspage.io, BetterStack, Instatus)

Servicios hospedados manejan la infraestructura, monitoreo de uptime y gestión de suscriptores. Cuestan dinero pero eliminan el riesgo de que tu página de estado caiga con tu API. Úsalos si no quieres construir y mantener infraestructura separada.

Self-hosted (Cachet, Upptime)

Opciones self-hosted como Cachet o Upptime corren en GitHub Pages o un host estático simple. Son gratuitas pero requieren setup y mantenimiento. Upptime usa GitHub Actions para monitoreo y almacena historial en el repositorio.

Páginas de estado solo internas

Para servicios internos, usa una página más simple sin suscripciones ni historial público de incidentes. Un canal de Slack con alertas automatizadas suele bastar. Consulta la Guía de Alert Management para estrategias de alerting.

Lectura Adicional

• Google SRE — Managing Incidents — el estándar de comunicación
• Atlassian — Incident Communication — mejores prácticas de status page