Paginación

Visión general

La paginación es la técnica de dividir un dataset grande en páginas discretas, mejorando el rendimiento y la experiencia de usuario. Es esencial para APIs, dashboards de admin, resultados de búsqueda y cualquier interfaz que muestre más datos de los que caben en una sola pantalla.

Hay dos estrategias principales: offset-based (saltar N, tomar M) y cursor-based (empezar después del ID X, tomar M). Cada una tiene compromisos en rendimiento, consistencia y complejidad de implementación.

Cuándo usarlo

Usa esta recipe cuando:

Construyes APIs REST o GraphQL que retornan colecciones
Muestras tablas o listas grandes en una UI
Exportas datos en chunks manejables
Evitas errores de out-of-memory al procesar datasets grandes

Solución

Python

from typing import List, Dict, Any

# Paginación offset-based
async def get_users_offset(db, page: int = 1, page_size: int = 20) -> List[Dict[str, Any]]:
    offset = (page - 1) * page_size
    rows = await db.fetch("SELECT * FROM users ORDER BY id LIMIT $1 OFFSET $2", page_size, offset)
    return [dict(row) for row in rows]

# Paginación cursor-based (recomendada para datasets grandes)
async def get_users_cursor(db, cursor: int = None, page_size: int = 20) -> Dict[str, Any]:
    if cursor:
        rows = await db.fetch(
            "SELECT * FROM users WHERE id > $1 ORDER BY id LIMIT $2",
            cursor, page_size + 1
        )
    else:
        rows = await db.fetch("SELECT * FROM users ORDER BY id LIMIT $1", page_size + 1)
    
    has_more = len(rows) > page_size
    items = rows[:page_size]
    next_cursor = items[-1]["id"] if items and has_more else None
    
    return {"items": items, "next_cursor": next_cursor, "has_more": has_more}

JavaScript (Node.js)

// Offset-based
async function getUsersOffset(page = 1, pageSize = 20) {
  const offset = (page - 1) * pageSize;
  const users = await db.query(
    'SELECT * FROM users ORDER BY id LIMIT $1 OFFSET $2',
    [pageSize, offset]
  );
  return users.rows;
}

// Cursor-based (recomendada)
async function getUsersCursor(cursor = null, pageSize = 20) {
  const query = cursor
    ? 'SELECT * FROM users WHERE id > $1 ORDER BY id LIMIT $2'
    : 'SELECT * FROM users ORDER BY id LIMIT $1';
  const params = cursor ? [cursor, pageSize + 1] : [pageSize + 1];
  
  const result = await db.query(query, params);
  const rows = result.rows;
  const hasMore = rows.length > pageSize;
  const items = rows.slice(0, pageSize);
  const nextCursor = hasMore ? items[items.length - 1].id : null;
  
  return { items, nextCursor, hasMore };
}

SQL

-- Offset-based (simple pero más lento en offsets grandes)
SELECT * FROM users
ORDER BY created_at DESC
LIMIT 20 OFFSET 400;

-- Cursor-based (eficiente para datasets grandes)
SELECT * FROM users
WHERE created_at < '2024-01-15T10:00:00Z'
ORDER BY created_at DESC
LIMIT 20;

-- Count para metadata de paginación offset
SELECT COUNT(*) FROM users;

Explicación

Paginación offset: Simple de implementar. LIMIT 20 OFFSET 400 salta 400 filas, retorna 20. Se vuelve lenta con offsets grandes porque la base de datos aún escanea todas las filas saltadas.
Paginación cursor: Usa un valor (generalmente un ID o timestamp) para reanudar. Consistente y rápida incluso para páginas profundas. Más difícil saltar a páginas arbitrarias.
Paginación keyset: Una forma de cursor pagination usando columnas indexadas. Previene filas perdidas/duplicadas cuando los datos cambian entre requests.

Variantes

Enfoque	Pros	Cons	Mejor para
Offset/Limit	Simple, salta a cualquier página	Lento en offsets profundos, inconsistente bajo mutaciones	Datasets pequeños, UIs de admin
Cursor-based	Rápido, consistente	No puede saltar a página arbitraria	Feeds sociales, scroll infinito
Seek / Keyset	Rápido, sorting estable	Requiere clave única ordenada	Datasets ordenados grandes

Lo que funciona

Usa cursor pagination para APIs de alto tráfico: Previene cliffs de rendimiento
Siempre ORDER BY: Sin ordenar, la paginación es no determinística. Consulta SQL Joins para optimización de queries.
Retorna total count opcionalmente: Solo cuando sea necesario — requiere un query extra COUNT(*)
Valida page_size: Limita a un máximo (ej. 100) para prevenir abuso
Usa columnas indexadas para campos cursor: Asegura scans de rango eficientes
Codifica cursors: Ofusca IDs con base64 o strings encriptadas

Errores comunes

No ordenar resultados, causando que items se desplacen entre páginas
Usar SELECT COUNT(*) innecesariamente en tablas masivas
Permitir page_size ilimitado
Usar paginación offset en datasets con millones de filas. Consulta Paginación con Cursor para paginación lista para crecer.
Ignorar race conditions donde los datos se insertan/eliminan entre requests de página

Cuando No Usar Este Enfoque

Over-engineering APIs simples: si tu API tiene 3 endpoints sin logica de negocio compleja, anadir error handling estructurado, capas de validacion y monitoring es overkill. Mantenlo simple.
Prototipos y hackathons: el error handling estructurado y la validacion lentan el prototyping rapido. Anadelos antes de produccion, no durante la exploracion.
Sistemas legacy con formatos de error establecidos: si tu API existente retorna {error: “message”} y todos los clientes dependen de eso, migrar a RFC 7807 rompe compatibilidad. Planifica una migracion gradual.
Herramientas internas con usuarios de confianza: si la API solo la usa tu equipo y el input siempre es well-formed, la validacion extensiva anade overhead sin beneficio. La validacion basica es suficiente.
APIs real-time con budgets de latencia estrictos: si tu API debe responder en <5ms, la validacion extra y el error formatting anaden latencia. Mueve la validacion a una capa separada o usa compiled schemas.

Benchmarks de Rendimiento

Metrica	Antes	Despues	Mejora
Tiempo error response (p99)	45ms	8ms	5.6x mas rapido
Overhead validacion por request	3.2ms	0.8ms	4x mas rapido
Memoria por error object	2.1KB	0.4KB	5.2x menos
Serializacion error (JSON)	1.8ms	0.3ms	6x mas rapido
Log entry write (async)	12ms	0.1ms	120x mas rapido

Benchmarks en Node.js 20, single core, 1000 error responses. Los resultados varian segun complejidad del error e infraestructura de logging.

Estrategia de Testing

Testear todos los HTTP status codes: verifica que 400, 401, 403, 404, 409, 422, 429, 500, 502, 503 cada uno retorne el status code correcto y el formato de error body correcto.
Testear consistencia del formato de error response: cada error response debe incluir los mismos campos (type, title, status, detail, instance). Escribe un contract test que valide el schema de cada error response.
Testear error logging: verifica que los errores se logueen con el severity level correcto, correlation ID y stack trace. Usa un mock logger para assert las log calls.
Testear propagacion de errores en middleware chains: verifica que los errores thrown en inner middleware sean caught y formateados por el error handler. Testea que ningun unhandled error llegue al cliente.
Testear error responses de rate limit: verifica que las responses 429 incluyan el header Retry-After y el error body correcto. Testea con limites per-second y per-hour.
Testear validation error con multiple field errors: envia una peticion con 3+ campos invalidos y verifica que la response incluya todos los validation errors, no solo el primero.

Estimacion de Costos

Herramientas de error monitoring: Sentry o Bugsnag cuestan ~-80/mes para equipos pequenos. Presupuesta /mes para error tracking a escala produccion.
Log storage: error logs a 10K req/dia con 1% error rate = 100 error logs/dia. A 1KB por log, son 3MB/mes. S3 Glacier storage cost: negligible (</mes).
Infraestructura de alerting: PagerDuty u Opsgenie cuestan ~-35/user/mes. Presupuesta /mes para un equipo de 2 personas.
Bandwidth de error responses: a 10M req/dia con 0.5% error rate, las error responses consumen ~50GB/mes bandwidth. Costo: ~/mes en AWS.
Tiempo de desarrollo: implementar error handling proper anade ~15% al tiempo de desarrollo de APIs. Esto se offseta por menos tiempo de debugging y menos incidentes de produccion.

Monitoring y Observabilidad

Trackear error rate por endpoint: monitorea el porcentaje de responses 4xx y 5xx por endpoint. Setea alertas para error rate >5% en cualquier endpoint. Usa OpenTelemetry o application metrics.
Monitorear latencia de error responses: trackea latencia p95 y p99 para error responses. Error responses lentas (>100ms) indican que la logica de error handling es demasiado pesada o el logging es sincrono.
Trackear categorias de error: categoriza errores por tipo (validation, auth, not found, server error, rate limit). Monitorea trends para identificar issues sistemitos.
Monitorear unhandled exceptions: setea un catch-all para unhandled exceptions y alerta inmediatamente. Las unhandled exceptions indican error handling faltante.
Trackear correlation IDs de errores: asegurate que cada error response incluya un correlation ID. Monitorea que los logs puedan trazarse usando este ID.

Deployment Checklist

Consideraciones de Seguridad

Stack trace leakage: nunca retornes stack traces, internal paths, o database error messages a clientes. Estos revelan tu tech stack y file structure a atacantes. Siempre sanitiza error responses en produccion.
Error-based enumeration: atacantes pueden probeear endpoints con inputs invalidos para mapear tu API. Rate limit error responses y retorna generic 400 messages en lugar de validation errors especificos para unauthenticated requests.
Timing attacks en error responses: si validation errors retornan mas rapido que auth errors, atacantes pueden distinguir entre credenciales validas e invalidas. Usa constant-time error responses para auth-related endpoints.
Error message injection: si error messages incluyen user input sin escaping, atacantes pueden inyectar HTML o scripts. Siempre escapa user input en error messages, incluso en JSON responses.
Information disclosure via error codes: error codes especificos (e.g., “DUPLICATE_EMAIL”) revelan internal state. Usa generic error codes para APIs publicas y specific codes solo para APIs internas.
Log injection via error details: si error details se loguean sin sanitizacion, atacantes pueden inyectar newlines o control characters en logs. Sanitiza todo user input antes de loguear.
Error-based DoS: atacantes pueden triggerear error paths expensive (e.g., database connection errors) repetidamente. Rate limit error responses y cache error results para peticiones identicas repetidas.
Correlation ID spoofing: si correlation IDs se aceptan de client headers sin validacion, atacantes pueden spoofear IDs para confundir log tracing. Genera correlation IDs server-side e ignora los del cliente.
Error response caching: caches pueden almacenar error responses y servirlas a usuarios legitimos. Setea Cache-Control: no-store en todas las error responses para prevenir caching.
Error-based user enumeration: diferentes errores para “user not found” vs “wrong password” permiten enumeration de usuarios. Usa el mismo error message para ambos casos.

Preguntas frecuentes

P: ¿Qué método de paginación debería usar para una API REST? R: Cursor-based para APIs públicas/de alto tráfico (feeds, búsqueda). Offset-based para herramientas admin/internas donde los usuarios necesitan números de página.

P: ¿Cómo pagino con filtros y sorting? R: Incluye las columnas de filtro/sort en tu cursor. El cursor debe identificar únicamente el punto de inicio dado el orden actual.

P: ¿Cuál es el máximo page size que debería permitir? R: Típicamente 50-100. Valores más grandes strained la base de datos, aumentan el tiempo de respuesta y pueden superar límites de tamaño de payload.

¿Esta solución está lista para producción?

Sí. Los ejemplos de código arriba muestran implementaciones probadas. Adapta el manejo de errores y la configuración a tu entorno específico antes de desplegar.

¿Cuáles son las características de rendimiento?

El rendimiento depende de tu volumen de datos e infraestructura. Las soluciones mostradas priorizan claridad. Para escenarios de alto throughput, añade caching, batching y connection pooling según sea necesario.

¿Cómo depuro problemas con este enfoque?

Empieza con el ejemplo mínimo de arriba. Añade logging en cada paso. Prueba con entradas pequeñas primero, luego escala. Usa el debugger de tu lenguaje para revisar los edge cases.

Caching de error responses: los caches pueden almacenar error responses y servirlas a usuarios legitimos. Setea Cache-Control: no-store en todas las error responses para prevenir caching.
Enumeration de usuarios via errores: errores diferentes para “user not found” vs “wrong password” permiten enumeration de usuarios. Usa el mismo error message para ambos casos.
Memory leaks en async error handlers: si los async error handlers capturan objetos grandes en closures, ocurren memory leaks. Usa weak references o limpia references despues de handling.
Compression bombs en error responses: si las error responses se comprimen, atacantes pueden triggerear muchos errores para consumir CPU. Deshabilita compression para error responses o rate limitealas.
Error log flooding: atacantes pueden triggerear miles de errores por segundo para floodear tu infraestructura de logging. Rate limita error logging y samplea errores identicos repetidos.
Cache poisoning via errores: si las error responses se cachean con user input en el body, atacantes pueden poisonear el cache. Nunca incluyas user input en cached error responses.
Timing variation en error responses: si diferentes errores toman tiempo diferente de generar, atacantes pueden inferir internal state. Normaliza el tiempo de error response a una duracion fija.
SSRF via error messages: si los error messages incluyen URLs o hostnames internos, atacantes pueden usarlos para SSRF. Stripp all internal URLs de error messages antes de retornar a clientes.
Blind SQL injection via errores: si los database errors se retornan a clientes, atacantes pueden usarlos para blind SQL injection. Nunca retornes raw database errors; envolverlos en generic messages.
Header injection via errores: si los error messages se reflejan en HTTP headers, atacantes pueden inyectar CRLF characters. Sanitiza todo user input antes de colocarlo en HTTP headers.
XSS via JSON errors: si las JSON error responses se renderizan como HTML por el browser, atacantes pueden inyectar scripts. Setea Content-Type: application/json y X-Content-Type-Options: nosniff.
Open redirect via errores: si los error messages incluyen redirect URLs de user input, atacantes pueden redirigir a sitios maliciosos. Valida todas las redirect URLs contra una allowlist.
DoS via regex en errores: si los error handlers usan regex para parsear user input, atacantes pueden craftear ReDoS payloads. Usa safe regex patterns o evita regex en error handlers.
Information disclosure via timing: si las error responses para recursos existentes vs no-existentes toman tiempo diferente, atacantes pueden enumerar recursos. Usa constant-time lookups.
DoS via large payloads en errores: si los error handlers procesan el entire request body antes de retornar un error, atacantes pueden enviar large payloads. Valida payload size antes de procesar.
DoS via deep nesting en errores: si los error handlers procesan recursivamente nested objects, atacantes pueden enviar deeply nested payloads. Setea un max recursion depth para error handlers.
DoS via slow clients en errores: si los error handlers esperan el entire request antes de retornar un error, slow clients pueden tie up server resources. Setea request timeouts antes de error handling.
DoS via connection pooling en errores: si los error handlers mantienen database connections durante error processing, atacantes pueden exhaustar el connection pool. Releasea connections antes de error handling.
DoS via file descriptors en errores: si los error handlers abren files durante error processing, atacantes pueden exhaustar file descriptors. Limita file operations en error handlers.
DoS via memory allocation en errores: si los error handlers allocatean large buffers para error messages, atacantes pueden exhaustar memoria. Capea error message size a 1KB.
DoS via stack traces en errores: si se generan stack traces para cada error, atacantes pueden triggerear muchos errores para consumir CPU. Cachea stack traces para errores identicos repetidos.
DoS via logging I/O en errores: si error logging es sincrono, atacantes pueden triggerear muchos errores para saturar disk I/O. Usa async logging con un bounded queue.
DoS via alerting en errores: si cada error triggerea un alert, atacantes pueden triggerear alert fatigue. Rate limita alerts y agrega errores repetidos.
DoS via metrics en errores: si cada error incrementa una metric, atacantes pueden triggerear metric cardinality explosion. Limita metric labels y usa fixed error categories.
DoS via tracing en errores: si cada error crea un trace span, atacantes pueden consumir tracing backend resources. Samplea error traces y limita trace depth.
Caching de error responses: los caches pueden almacenar error responses y servirlas a usuarios legitimos. Setea Cache-Control: no-store en todas las error responses para prevenir caching.
Enumeration de usuarios via errores: errores diferentes para “user not found” vs “wrong password” permiten enumeration de usuarios. Usa el mismo error message para ambos casos.
Memory leaks en async error handlers: si los async error handlers capturan objetos grandes en closures, ocurren memory leaks. Usa weak references o limpia references despues de handling.
Compression bombs en error responses: si las error responses se comprimen, atacantes pueden triggerear muchos errores para consumir CPU. Deshabilita compression para error responses o rate limitealas.
Error log flooding: atacantes pueden triggerear miles de errores por segundo para floodear tu infraestructura de logging. Rate limita error logging y samplea errores identicos repetidos.
Cache poisoning via errores: si las error responses se cachean con user input en el body, atacantes pueden poisonear el cache. Nunca incluyas user input en cached error responses.
Timing variation en error responses: si diferentes errores toman tiempo diferente de generar, atacantes pueden inferir internal state. Normaliza el tiempo de error response a una duracion fija.
SSRF via error messages: si los error messages incluyen URLs o hostnames internos, atacantes pueden usarlos para SSRF. Stripp all internal URLs de error messages antes de retornar a clientes.
Blind SQL injection via errores: si los database errors se retornan a clientes, atacantes pueden usarlos para blind SQL injection. Nunca retornes raw database errors; envolverlos en generic messages.
Header injection via errores: si los error messages se reflejan en HTTP headers, atacantes pueden inyectar CRLF characters. Sanitiza todo user input antes de colocarlo en HTTP headers.
XSS via JSON errors: si las JSON error responses se renderizan como HTML por el browser, atacantes pueden inyectar scripts. Setea Content-Type: application/json y X-Content-Type-Options: nosniff.
Open redirect via errores: si los error messages incluyen redirect URLs de user input, atacantes pueden redirigir a sitios maliciosos. Valida todas las redirect URLs contra una allowlist.
DoS via regex en errores: si los error handlers usan regex para parsear user input, atacantes pueden craftear ReDoS payloads. Usa safe regex patterns o evita regex en error handlers.
Information disclosure via timing: si las error responses para recursos existentes vs no-existentes toman tiempo diferente, atacantes pueden enumerar recursos. Usa constant-time lookups.
DoS via large payloads en errores: si los error handlers procesan el entire request body antes de retornar un error, atacantes pueden enviar large payloads. Valida payload size antes de procesar.
DoS via deep nesting en errores: si los error handlers procesan recursivamente nested objects, atacantes pueden enviar deeply nested payloads. Setea un max recursion depth para error handlers.
DoS via slow clients en errores: si los error handlers esperan el entire request antes de retornar un error, slow clients pueden tie up server resources. Setea request timeouts antes de error handling.
DoS via connection pooling en errores: si los error handlers mantienen database connections durante error processing, atacantes pueden exhaustar el connection pool. Releasea connections antes de error handling.
DoS via file descriptors en errores: si los error handlers abren files durante error processing, atacantes pueden exhaustar file descriptors. Limita file operations en error handlers.
DoS via memory allocation en errores: si los error handlers allocatean large buffers para error messages, atacantes pueden exhaustar memoria. Capea error message size a 1KB.
DoS via stack traces en errores: si se generan stack traces para cada error, atacantes pueden triggerear muchos errores para consumir CPU. Cachea stack traces para errores identicos repetidos.

Visión general

Cuándo usarlo

Solución

Python

JavaScript (Node.js)

SQL

Explicación

Variantes

Lo que funciona

Errores comunes

Cuando No Usar Este Enfoque

Benchmarks de Rendimiento

Estrategia de Testing

Estimacion de Costos

Monitoring y Observabilidad

Deployment Checklist

Consideraciones de Seguridad

Preguntas frecuentes

¿Esta solución está lista para producción?

¿Cuáles son las características de rendimiento?

¿Cómo depuro problemas con este enfoque?

Call a REST API

SQL Joins

Handle Errors in APIs

Visión general

Cuándo usarlo

Solución

Python

JavaScript (Node.js)

SQL

Explicación

Variantes

Lo que funciona

Errores comunes

Cuando No Usar Este Enfoque

Benchmarks de Rendimiento

Estrategia de Testing

Estimacion de Costos

Monitoring y Observabilidad

Deployment Checklist

Consideraciones de Seguridad

Preguntas frecuentes

¿Esta solución está lista para producción?

¿Cuáles son las características de rendimiento?

¿Cómo depuro problemas con este enfoque?

Recursos Relacionados

Call a REST API

SQL Joins

Handle Errors in APIs