Errores comunes

Formato de error

Los errores de la API siguen el formato estándar de NestJS:

{
  "statusCode": 401,
  "message": "Invalid API credentials",
  "error": "Unauthorized"
}

Código	Significado	Qué revisar
`400`	Parámetros inválidos	Tipos y rangos de query/body (`page`, `per_page`, IDs, fechas)
`401`	No autenticado	Headers `X-API-KEY` y `X-API-SECRET`
`403`	Sin permiso	`tours:read`, `reservations:write`, partner inactivo o sin canal vinculado
`404`	No encontrado	Recurso inexistente (tour, booking UUID, etc.)
`409`	Conflicto	Sin cupo, hold expirado/cancelado, o conflicto de negocio
`422`	Validación de negocio	Body incompleto; passengers que no cuadran con `pax`; fecha/hora inválida
`429`	Rate limit	Demasiados requests; respeta `rateLimitPerMinute` de tu partner
`503`	Servicio no disponible	Vulcano SaaS interno no alcanzable desde Partners API

401 en todos los endpoints protegidos

403 en GET /tours

403 o Missing required permission: reservations:write

Verifica GET /me → permissions debe incluir reservations:write.
El partner debe tener canal Vulcano vinculado; si no: Partner is not linked to a Vulcano sale channel.

409 en POST /reservations

No hay disponibilidad para ese tour_id + date + time + pax.
Revisa availability en GET /tours y vuelve a intentar con menos pax u otro horario.

409 en POST /reservations/confirm

Hold expirado (expires_at pasado): crea una reservation nueva y, si ya cobraste, reembolsa.
Hold cancelado o sin cupo al confirmar.

422 en confirm por passengers

passengers es obligatorio.
La cantidad por type debe coincidir con el pax del hold.
Campos requeridos: type, name, lastname, email, birthday, identification.

404 en tours, zonas o reservations

Los filtros usan IDs de Vulcano; valida zone, category, countryId, tour_id.
En reservations, valida que el UUID exista y pertenezca a tu partner.

503 o timeouts

Prueba GET /health (Partners API) y GET /health/saas (conexión a Vulcano).
Si el hold falla con 503, el error real puede estar en SaaS; reporta timestamp y body.

Endpoint	Auth	Qué valida
`GET /health`	No	Partners API + base de datos
`GET /health/saas`	Sí	Conectividad con Vulcano SaaS interno

Al reportar un incidente, incluye: