Estado y errores de Summit Notify

Liveness

GET /health/live

Confirma que el proceso HTTP está ejecutándose. No comprueba dependencias.

{
  "status": "alive"
}

Responde 200 OK y no requiere autenticación.

Readiness

GET /health/ready

Comprueba PostgreSQL y el proveedor OpenID Connect con un timeout global de 3 segundos.

Respuesta disponible (200):

{
  "status": "ready",
  "database": "available",
  "oidc": "available"
}

Si falla una o ambas dependencias responde 503 Service Unavailable:

{
  "status": "not-ready",
  "database": "available",
  "oidc": "unavailable"
}

Estado del proceso API

GET /api/v1/status

{
  "name": "Summit Notify",
  "service": "notify-api",
  "status": "running"
}

No requiere autenticación, pero comparte el rate limiter de /api/v1.

Estados de entrega

Estado	Descripción
pending	Espera el primer intento o un reintento programado.
processing	Fue reclamada atómicamente por un worker.
submitted	AWS aceptó el mensaje WhatsApp y se esperan eventos posteriores.
sent	SMTP aceptó el correo o WhatsApp confirmó el envío.
failed	Alcanzó el máximo de intentos.

Un fallo no terminal vuelve a pending con backoff exponencial, limitado a 5 minutos. Cada intento incrementa attempts. last_error se limpia al marcar como enviada y conserva la causa más reciente durante fallos/reintentos.

Para correo, sent no implica lectura ni garantiza que no ocurra un rebote posterior. Los eventos SNS delivered y read de WhatsApp actualizan marcas de tiempo internas, pero mantienen el estado en sent.

Formato JSON de errores

La API responde normalmente:

{
  "error": "descripción del problema"
}

El mensaje puede utilizarse para diagnóstico, pero los clientes deben tomar decisiones principalmente con el estado HTTP.

Códigos HTTP

Código	Uso
200 OK	GET exitoso, test de cuenta aceptado o health check disponible.
201 Created	Cuenta o plantilla creada.
202 Accepted	Notificación validada y encolada.
204 No Content	Cuenta o plantilla eliminada.
400 Bad Request	JSON/UUID inválido, campo desconocido, validación o recurso relacionado inválido.
401 Unauthorized	Falta la credencial o no puede validarse.
403 Forbidden	Scope insuficiente u origen no autorizado por la cuenta.
409 Conflict	Conflicto de propiedad o ventana de servicio WhatsApp cerrada.
404 Not Found	Recurso inexistente o perteneciente a otro usuario.
429 Too Many Requests	Se agotó el bucket del token/IP.
500 Internal Server Error	Fallo interno o de persistencia.
502 Bad Gateway	El envío inmediato de prueba fue rechazado/falló.
503 Service Unavailable	Readiness falló por PostgreSQL u OpenID Connect.

Un body superior a 1 MiB se informa actualmente como 400 invalid request body.

Rate limiting

La API identifica el bucket por hash del Bearer token; sin token usa la IP. La configuración actual repone una solicitud por segundo, permite una ráfaga de 30 y elimina buckets inactivos después de 10 minutos.

429 es una excepción al formato JSON:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: text/plain; charset=utf-8

too many requests

Espera al menos el valor de Retry-After antes de volver a intentar.

Proveedor HTTP (no habilitado)

La entrega mediante proveedores HTTP no está habilitada actualmente. La información siguiente se conserva como referencia técnica para una posible habilitación futura.

El cliente de envío HTTP:

• usa un timeout de 15 segundos;
• envía Content-Type: application/json y Accept: application/json;
• acepta únicamente estados 2xx;
• incluye como máximo 4096 bytes del body de error en last_error.

Errores SMTP

Los fallos al construir remitente/destinatarios, crear el cliente, conectar, negociar TLS, autenticar o enviar se registran en last_error. El worker limita cada envío completo a 30 segundos.