Errores y códigos

Formato

Todos los errores de negocio responden el mismo cuerpo, con su código HTTP correspondiente:

{ "error": "Mensaje legible en español" }

Los mensajes están pensados para mostrarse al usuario final (son en español y nombran la entidad involucrada).

Códigos

HTTP	Cuándo	Cómo reaccionar
`400`	Datos inválidos de dominio (fecha pasada, zona de otro evento…)	No reintentar; corregir el payload
`401`	Sin token, token revocado o secreto inválido	Refrescar sesión con `/auth/refrescar` o reloguear
`403`	Rol insuficiente o sesión de participante en ruta de admin	Revisar el rol del usuario
`404`	Recurso no existe (o no pertenece al evento)	Tratar como inexistente, no es transitorio
`409`	Conflicto de estado o duplicado	Ver abajo: hay casos reintentables
`422`	Validación de schema (Elysia): tipo, formato, `format: uuid`	Corregir el payload; nunca reintentar igual
`429`	Rate limit por IP	Backoff exponencial; reintentar pasada la ventana
`500`	Falla inesperada	Reintentar con cuidado; revisar logs del servidor
`503`	DB no responde (solo en `/health`)	Revisar base de datos/conexión; el resto de rutas fallarían con `500`

Conflictos frecuentes (`409`)

Mensaje típico	Causa
`Ya existe un participante con ese email en el evento`	Duplicado en padrón
`El participante ya tiene reserva vigente`	Un participante = una vigente
`El lugar ya tiene reserva vigente`	Otro usuario llegó primero (carrera)
`El participante ya está en estado '…'`	Transición repetida
`La reserva ya tiene boleto`	Doble emisión
`No se puede eliminar: tiene registros asociados`	FK RESTRICT (p. ej. puerta con escaneos)
`Ya existe una mesa con ese número en el evento`	Único por evento
`El evento no admite reservas en estado 'borrador'`	Estado del ciclo de vida

Los 409 de carrera (lugares y grupos) son el caso reintentable: otro cliente ganó el mismo cupo; elige otro lugar o grupo.

Idempotencia

POST /reservas/ acepta idempotencyKey. Si repites la misma llave con el mismo cuerpo, la segunda llamada no crea otra reserva: devuelve la existente con un flag de repetida. Útil para reintentos de red:

curl -X POST http://localhost:5000/reservas/ \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $TOKEN" \
  -d '{"eventoId":"…","participanteId":"…","lugarId":"…","canal":"web","idempotencyKey":"mi-llave-1"}'

El resto de los POST de creación no son idempotentes: reintenta solo si la respuesta fue un error de red (no un 409/422).

Errores de base de datos

Los errores de Postgres (violaciones de constraint, FK RESTRICT, triggers) se traducen a los 4xx de arriba con mensajes propios; un error PG que no está contemplado llega como 500. El detalle del problema real vive en los logs del servidor, no en la respuesta.

Siguiente paso

→ Eventos y ciclo de vida