GUÍA: Códigos HTTP y Respuestas

Esta guía explica cómo usar correctamente los códigos HTTP en tus respuestas JSON y cómo estructurar tus controladores para que sean limpios, consistentes y reutilizables.

---

1. Formato estándar de respuesta JSON

{
  "status": "success",      // o "error", "not_found"
  "message": "Descripción del resultado",
  "data": { /* contenido */ } // opcional
}

2. Tabla de códigos HTTP y cuándo usarlos

Código	Tipo	Significado	Uso habitual
200	✅ Éxito	OK	Lecturas exitosas
201	✅ Éxito	Created	Recurso creado (POST o PUT)
204	✅ Éxito	No Content	Eliminación sin cuerpo de respuesta
400	❌ Cliente	Bad Request	Datos faltantes o inválidos
401	❌ Cliente	Unauthorized	No autenticado
403	❌ Cliente	Forbidden	Sin permisos
404	❌ Cliente	Not Found	Recurso no encontrado
409	❌ Cliente	Conflict	Conflicto (ej. duplicación)
422	❌ Cliente	Unprocessable Entity	Campos semánticamente incorrectos
500	🔴 Servidor	Internal Server Error	Error inesperado en backend

---

3. Respuestas reutilizables en backend

3.1 responseHelper (/src/utils/responseHelper.ts)

tsCopiarEditarimport { Response } from 'express';

export const responseHelper = {
  success: (res: Response, data: any, message = 'Éxito', statusCode = 200) =>
    res.status(statusCode).json({ status: 'success', message, data }),

  notFound: (res: Response, message = 'Recurso no encontrado') =>
    res.status(404).json({ status: 'not_found', message }),

  error: (res: Response, error: any, message = 'Error interno', statusCode = 500) => {
    console.error('[ERROR]', error);
    return res.status(statusCode).json({
      status: 'error',
      message,
      error: error instanceof Error ? error.message : String(error),
    });
  },
};

3.2 (Opcional) HttpStatus (/src/utils/HttpStatus.ts)

tsCopiarEditarexport const HttpStatus = {
  OK: 200,
  CREATED: 201,
  NO_CONTENT: 204,
  BAD_REQUEST: 400,
  UNAUTHORIZED: 401,
  FORBIDDEN: 403,
  NOT_FOUND: 404,
  CONFLICT: 409,
  UNPROCESSABLE: 422,
  SERVER_ERROR: 500,
};

---

4. Ejemplo de uso en un controlador

tsCopiarEditarimport { Request, Response } from 'express';
import { responseHelper } from '../utils/responseHelper';
// import { HttpStatus } from '../utils/HttpStatus'; // si lo usas

export const getUsuarios = async (req: Request, res: Response) => {
  try {
    const usuarios = await userService.getAll();

    if (!usuarios || usuarios.length === 0) {
      return responseHelper.notFound(res, 'No hay usuarios registrados');
    }

    return responseHelper.success(res, usuarios, 'Usuarios obtenidos');
  } catch (error) {
    return responseHelper.error(res, error, 'Error al obtener usuarios');
  }
};

---

5. Beneficios de esta estructura

• ✅ Respuestas consistentes

• ✅ Código limpio y libre de duplicación

• ✅ Fácil de escalar y mantener

• ✅ Ideal para documentación automática con Swagger u otros

---

6. Siguientes pasos recomendados

• Implementa un BaseController si usas clases y herencia

• Añade validaciones con librerías como zod, joi o class-validator

• Integra logs con winston, pino o alguna solución estructurada

• Agrega controles de autenticación/autorización (JWT, OAuth)

---

Desarrollado como guía técnica para backend moderno en Node.js + TypeScript 🛠️

🚀 Cómo usar esta página en GitBook

1. En tu espacio de GitBook, crea una nueva página o entrada bajo la carpeta de documentación técnica.

2. Copia y pega el contenido del bloque Markdown superior.

3. Ajusta si deseas agregar más ejemplos o notas personalizadas.

4. Organízalo con tu índice de contenido para fácil referencia.

---

✅ Cómo usar este helper en tu backend

• Copia los archivos responseHelper.ts y HttpStatus.ts a tu carpeta src/utils/.

• Importa y usa responseHelper en todos tus controladores:

  responseHelper.success(res, data, 'Mensaje')
  responseHelper.notFound(res, 'No encontrado')
  responseHelper.error(res, error, 'Mensaje de error')

• Opcionalmente usa HttpStatus.OK en vez de números literales.