Módulo 1: Google Sheets

Troubleshooting de Google Sheets

Descripción de la cápsula

Tu workflow funciona perfecto en la prueba. Lo activas, pasan tres días, y un lunes te das cuenta de que no escribió nada el fin de semana. O escribió, pero las fechas salieron como números raros. O de repente da un error que dice "Quota exceeded".

Bienvenido a los problemas que no son de lógica sino de la realidad de trabajar con la API de Google. Tu workflow está bien diseñado; lo que falla es el roce con límites, formatos y permisos del mundo real.

Esta cápsula es tu manual de diagnóstico. No vas a aprender una operación nueva — vas a aprender a reconocer y resolver los cinco problemas que el 95% de los workflows de Google Sheets encuentran en producción: rate limits, formatos de fecha, números que se vuelven texto, permisos caducados, y la hoja "que se movió".

Lo que vas a aprender

Al terminar esta cápsula serás capaz de:

✅ Reconocer y resolver rate limits de la API de Google Sheets
✅ Manejar formatos de fecha para que no se rompan entre n8n y la hoja
✅ Evitar que los números se conviertan en texto (y viceversa)
✅ Diagnosticar errores de permisos y credenciales caducadas
✅ Sobrevivir a cambios en la estructura de la hoja
✅ Leer los mensajes de error de Google y saber qué hacer con cada uno

Problema 1: Rate limits (Quota exceeded)

El síntoma

Un error con texto como: Quota exceeded, 429 Too Many Requests, o Rate Limit Exceeded.

Por qué pasa

Google Sheets tiene cuotas: un límite de cuántas peticiones puedes hacer por minuto. Los números cambian, pero a nivel práctico el límite ronda los 60 lecturas/escrituras por minuto por usuario (consulta el enlace de recursos para el dato vigente). Tu workflow se pasa de ese límite cuando:

Procesa muchos items y hace una operación de Sheets por item (300 leads → 300 escrituras)
Tienes varios workflows golpeando Sheets al mismo tiempo
Un loop que lee/escribe en cada vuelta

Las soluciones

1. Operaciones en lote (lo más efectivo). En lugar de Append fila por fila, deja que el nodo reciba todos los items juntos y los escriba en una sola operación. El nodo de Google Sheets puede escribir múltiples filas en una llamada — no fuerces un loop que escribe de a una.

2. Reducir la frecuencia. Si un Schedule corre cada minuto y cada corrida hace 50 operaciones, baja a cada 15 minutos.

3. Agregar un pequeño retraso. Si de verdad necesitas procesar item por item, un nodo Wait corto entre operaciones reparte la carga.

4. Reintentar con backoff. Configura el nodo para reintentar si falla (Settings → Retry On Fail). Combinado con error handling — tema de G10 — el workflow se recupera solo de un rate limit temporal.

El principio: trata cada llamada a la API de Google como cara. El mejor workflow no es el que reintenta bien — es el que hace menos llamadas.

Problema 2: Fechas que se rompen

El síntoma

Escribes una fecha y en la hoja aparece:

2026-05-14T15:03:00.000-06:00 (el objeto completo, ilegible)
45791 (un número serial — el formato interno de fechas de Sheets)
14/05/2026 cuando esperabas 05/14/2026 (o al revés)

Por qué pasa

n8n maneja fechas como objetos DateTime. Google Sheets las guarda como números seriales pero las muestra según el formato regional de la hoja. Entre esos dos mundos hay fricción.

Las soluciones

1. Formatea la fecha a texto antes de escribir. No mandes el objeto DateTime crudo:

{{ $now.toFormat('yyyy-LL-dd') }}        → 2026-05-14
{{ $now.toFormat('yyyy-LL-dd HH:mm') }}  → 2026-05-14 15:03
{{ $now.toFormat('dd/LL/yyyy') }}        → 14/05/2026

2. Elige un formato y sé consistente. yyyy-LL-dd (ISO) es el más seguro: se ordena bien, no hay ambigüedad día/mes, y los lookups funcionan.

3. Configura el formato de la columna en la hoja. Si quieres que Sheets trate la columna como fecha real (para ordenar, hacer cálculos), formatea la columna como Fecha en Google Sheets y escribe en un formato que reconozca.

Recomendación práctica: para la mayoría de casos de negocio, escribe las fechas como texto en formato yyyy-LL-dd. Es predecible, se ordena correctamente y nunca te sorprende. Solo necesitas fechas "reales" en la hoja si vas a hacer cálculos con fórmulas de Sheets.

Problema 3: Números que se vuelven texto (y al revés)

El síntoma

Guardas 100 y al leerlo de vuelta es "100" (texto) → tus cálculos fallan
Guardas un teléfono 0445512345678 y la hoja lo muestra 445512345678 (se comió el cero)
Un código 00042 se vuelve 42

Por qué pasa

Google Sheets interpreta lo que escribes. Si parece número, lo trata como número — y los números no tienen ceros a la izquierda. Si parece texto, lo deja como texto.

Las soluciones

1. Para identificadores (teléfonos, códigos, SKUs): trátalos como texto. Formatea esas columnas en la hoja como Texto sin formato (Formato → Número → Texto sin formato). Así Sheets no se come los ceros.

2. Para valores con los que vas a calcular (precios, cantidades): asegúrate de que sean números. Si te llegan como texto, conviértelos en el mapeo:

{{ Number($json.price) }}

3. Sé consciente al leer. Cuando lees de Sheets, los valores pueden venir como texto. Si vas a sumar o comparar, convierte explícitamente.

Regla: decide para cada columna si es un identificador (texto, aunque parezca número — teléfono, código, ID) o un valor numérico (número, para calcular — precio, cantidad). Formatea la columna en la hoja según esa decisión.

Problema 4: Permisos y credenciales

El síntoma

The caller does not have permission
Insufficient permission
El workflow funcionaba y de repente todas las operaciones de Sheets fallan
La credencial aparece con un ícono de advertencia

Por qué pasa

El token OAuth caducó o fue revocado. Pasa si cambiaste tu contraseña de Google, revocaste el acceso, o el token simplemente expiró.
Perdiste acceso a la hoja. El dueño dejó de compartírtela, o cambió tu nivel de "editor" a "lector".
La hoja se borró o se movió a una unidad a la que no tienes acceso.

Las soluciones

1. Reconecta la credencial. En n8n → Credentials → tu credencial de Google Sheets → vuelve a hacer el flujo OAuth (Sign in with Google). Esto renueva el token.

2. Verifica el acceso a la hoja. Abre la hoja directamente en tu navegador con la misma cuenta de Google de la credencial. Si no puedes abrirla o solo puedes verla, ese es el problema — pide acceso de editor.

3. Revisa que la hoja siga existiendo. Si alguien la borró o la movió, el ID que tu workflow usa ya no es válido.

Prevención: las credenciales OAuth de Google se mantienen mejor si la cuenta es estable (no cambias contraseña seguido) y si la hoja vive en una cuenta que controlas, no en una compartida que alguien más puede dejar de compartirte.

Problema 5: La hoja "se movió"

El síntoma

El workflow escribe en las columnas equivocadas. O da error de "columna no encontrada". Ayer funcionaba.

Por qué pasa

Alguien editó la estructura de la hoja:

Renombró una columna (email → contact_email)
Insertó una columna en medio, corriendo todas las demás
Reordenó las columnas
Borró la fila de encabezados o la movió

Recuerda de la cápsula 02: n8n lee la fila 1 como encabezados. Si esa fila cambia, todos los mapeos que dependían de ella se desajustan.

Las soluciones

1. Trata los encabezados como un contrato. La fila 1 de una hoja conectada a workflows no se toca casualmente. Si tu equipo comparte la hoja, ponlo por escrito: "esta hoja alimenta automatizaciones, no cambies los encabezados".

2. Apunta por nombre, no por posición. El nodo de Google Sheets ya mapea por nombre de columna, no por letra (A, B, C). Eso te protege de reordenamientos — siempre que el nombre no cambie.

3. Si la estructura va a cambiar, planéalo. Cambia la hoja y actualiza los workflows en la misma sesión. No dejes el desajuste "para después".

4. Considera una hoja dedicada. Las hojas que alimentan automatizaciones idealmente no son las mismas que la gente edita a mano todo el día. Una hoja "de integración" estable, alimentada por workflows, separada de la hoja "de trabajo".

Cómo leer un error de Google Sheets

Cuando el nodo falla, n8n te muestra el error. Aprende a clasificarlo rápido:

El error menciona...	Es un problema de...	Ve a...
`quota`, `rate limit`, `429`	Demasiadas llamadas	Problema 1
`permission`, `403`, `caller does not have`	Permisos / credencial	Problema 4
`not found`, `404`, `unable to parse range`	Hoja/columna que cambió o no existe	Problema 5
`invalid`, formato, fecha	Formato de datos	Problemas 2 y 3
`unauthorized`, `401`, `token`	Credencial caducada	Problema 4

Primer reflejo siempre: lee el texto del error completo. Google suele decir bastante claro qué pasó — el problema es que no lo leemos, asumimos.

Trampas comunes

Trampa 1: Diseñar el workflow asumiendo que la API nunca falla

Qué pasa: Tu workflow no tiene ningún manejo de error. El primer rate limit lo detiene y nadie se entera.

Cómo evitar: Toda integración con un servicio externo debe asumir que el servicio fallará a veces. Reintentos y manejo de error son tema de G10, pero el mindset empieza aquí.

Trampa 2: Probar con 3 filas y desplegar para 3,000

Qué pasa: Funciona perfecto con tu hoja de prueba de 3 filas. En producción, con 3,000, choca con rate limits o tarda muchísimo.

Cómo evitar: Prueba con un volumen parecido al real. Si producción tiene miles de filas, tu hoja de prueba también debe tenerlos.

Trampa 3: Asumir que el formato de fecha "se entiende solo"

Qué pasa: Escribes fechas sin formatear y cada una sale distinta según de dónde vino.

Cómo evitar: Formato de fecha explícito y consistente en todo el workflow. Decide yyyy-LL-dd y úsalo en todos lados.

Trampa 4: Culpar a n8n cuando es Google

Qué pasa: Pierdes una hora revisando tu workflow cuando el error decía claramente "permission denied" — era la credencial.

Cómo evitar: Lee el error primero. Clasifícalo con la tabla de arriba. La mitad de los problemas de Sheets no están en tu lógica.

Ejercicio: diagnostica cinco errores

Objetivo: practicar la clasificación rápida de errores.

Tu tarea

Para cada mensaje de error, di (1) qué problema es y (2) cuál es el primer paso para resolverlo:

Error: Quota exceeded for quota metric 'Write requests'
Error: The caller does not have permission
En la hoja, la columna phone muestra 5512345678 pero escribiste 05512345678
Error: Unable to parse range: Sheet1!A:E
La columna total tiene "1500" y tu nodo de cálculo da error al sumarla

Ver respuestas

Rate limit (Problema 1). Primer paso: revisar si haces operaciones fila por fila y cambiar a lote, o bajar la frecuencia.
Permisos (Problema 4). Primer paso: reconectar la credencial OAuth y verificar acceso de editor a la hoja.
Número que se comió el cero (Problema 3). Primer paso: formatear la columna phone como Texto sin formato en la hoja.
Hoja/rango que cambió (Problema 5). Primer paso: verificar que la pestaña se siga llamando Sheet1 y que la hoja exista.
Número guardado como texto (Problema 3). Primer paso: convertir con {{ Number($json.total) }} antes de calcular.

Resumen y siguiente paso

Los problemas de producción con Sheets casi nunca son de lógica — son de rate limits, formatos y permisos
Rate limits: escribe en lote, reduce frecuencia, trata cada llamada como cara
Fechas: formatea a texto explícito (yyyy-LL-dd) antes de escribir — no mandes el objeto crudo
Números vs texto: decide por columna si es identificador (texto) o valor (número) y formatea la columna acorde
Permisos: reconecta la credencial OAuth, verifica acceso de editor a la hoja
Estructura: los encabezados son un contrato — no se tocan casualmente; usa una hoja dedicada a integraciones
Leer el error primero: la tabla de clasificación te dice en qué problema estás antes de revisar tu workflow

Antes de avanzar deberías poder:

Reconocer un rate limit y saber 2 formas de resolverlo
Escribir fechas en un formato consistente
Clasificar un mensaje de error de Google en segundos

Lo que sigue (cápsula 08):

Es hora de juntar todo. El mini-proyecto: un workflow que actualiza una hoja automáticamente desde un evento. Vas a usar el patrón "buscar antes de actuar" (cápsula 03), Update or Append (cápsula 05), mapeo manual (cápsula 06) y diseño defensivo (cápsula 07) — todo en un solo workflow funcional.

Recursos adicionales

Google Sheets API limits - Cuotas oficiales vigentes.
n8n Error Handling Docs - Reintentos y manejo de fallos (se profundiza en G10).
Luxon formatting tokens - Todos los tokens para formatear fechas con toFormat().

Creado: Mayo 14, 2026 Versión: 1.0

← AnteriorMapeo de Datos Siguiente →Mini-Proyecto: Actualizar una Hoja desde un Evento