Convenciones HTTP y Formato de Errores

Convenciones HTTP y Formato of Errores

El backend de uunit9 utiliza respuestas en formato JSON estandarizado para la gestión de errores y validaciones (apps/api/src/lib/http.ts).

Estructura de Respuestas de Error

1. Error de Validación Zod (400 Bad Request)

Cuando los datos enviados en el cuerpo de la solicitud no cumplen con el esquema Zod esperado:

{
  "error": "validation_error",
  "issues": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["name"],
      "message": "Required"
    }
  ]
}

2. Error de JSON Malformado (400 Bad Request)

{
  "error": "invalid_json"
}

3. Error de Sesión o Autenticación (401 Unauthorized)

{
  "error": "unauthorized"
}

4. Error de Permisos insipientes (403 Forbidden)

{
  "error": "forbidden",
  "message": "Se requiere rol de administrador u owner"
}

5. Recurso No Encontrado (404 Not Found)

{
  "error": "not_found"
}

6. Conflicto de Negocio (409 Conflict)

Ejemplo al intentar abrir una caja habiendo otra sesión abierta:

{
  "error": "session_already_open"
}

Middleware de Autenticación y Contexto

Toda solicitud autenticada pasa por el middleware de sesión que valida la cookie/token y expone en el contexto de Hono (c.get(...)):

• orgId: Identificador de la organización del usuario.
• userId: ID del usuario autenticado.
• role: Rol activo (owner, admin, waiter, kitchen, etc.).