Google Sheets es la base de datos no oficial de la mayoría de las PyMEs que conocemos. Toda la información útil está ahí: clientes, pedidos, stock, reportes. Cuando aparece un LLM en la ecuación y alguien quiere conectar Sheets con OpenAI o Claude, vemos los mismos errores una y otra vez.
Este post resume los cinco que más tiempo nos cuestan cuando auditamos proyectos de clientes. No son fallas del stack; son decisiones de diseño que suenan razonables en el momento y después rompen cosas.
Error 1: esperar JSON determinístico sin forzar el formato
Es el error más común y el que más daño hace. Alguien arma un prompt del tipo "devolveme los datos como JSON con estos campos" y confía en que el modelo siempre responda igual.
Durante algunas corridas funciona. Después, en una corrida cualquiera, el modelo devuelve JSON con una coma extra, o mete una explicación antes del JSON, o devuelve los campos en otro orden. El código que espera parsearlo rompe y queda sin saber qué hacer.
La solución es usar la funcionalidad de structured outputs o response format con schema que ofrecen los APIs modernos. No confíes en que el modelo va a respetar el formato porque le pediste amablemente; obligalo con un schema. Si estás con una versión vieja del API que no lo soporta, validá siempre la salida con zod o similar antes de usarla, y tené un camino de fallback cuando no parsea.
Error 2: hardcodear IDs de hojas y rangos
Vemos esto constantemente: el workflow apunta a un spreadsheetId específico, al rango Sheet1!A2:F1000, y todo está clavado en el código o en variables de entorno.
El problema aparece cuando alguien del negocio renombra la hoja (muy común), cambia el orden de las columnas, o crea una copia de la planilla para un mes nuevo. El workflow no falla con error claro; falla con datos equivocados. A veces nadie lo nota durante días.
La mejor práctica es usar el nombre de la hoja como referencia (no el índice), leer por headers y no por columnas fijas, y validar antes de cada ejecución que los headers esperados estén presentes. Si alguien rompe la estructura, el workflow falla rápido y con mensaje claro, no silencioso.
Error 3: no manejar rate limits ni reintentos
Google Sheets tiene límites de lectura y escritura por minuto. OpenAI y Claude también. Cuando los encadenás sin cuidado, con un volumen moderado empezás a pegar contra los límites y a perder datos.
El error típico es tratar cada fila como una llamada independiente sin considerar cuántas estás haciendo por minuto. El workflow corre bien con 10 filas, se rompe con 500, y nadie sabe por qué.
Dos cosas mínimas que tienen que estar: batching (agrupá las lecturas y escrituras a Sheets en lotes grandes en vez de una por una) y backoff exponencial con retry en las llamadas al LLM. Si usás n8n o Make hay nodos específicos para eso; si estás en código, envolvé las llamadas en una librería de retry razonable.
Error 4: concatenar datos al prompt sin schema de validación
La tentación es pasar la fila de Sheets directa al prompt: "Analizá este cliente: ". El modelo devuelve algo, lo mostrás o lo guardás, seguís.
El problema es doble. Primero, nadie valida que los datos que entran al prompt sean los que esperás; si alguien pegó una fila con caracteres raros o celdas vacías, el prompt se contamina y la salida es basura. Segundo, no hay forma de auditar después qué datos exactos generaron qué respuesta, porque la fila fue una foto del momento.
La solución no es complicada: definí un schema de entrada (con zod, pydantic, lo que sea), validá cada fila antes de pasarla al modelo, y registrá en algún lado (un log, otra hoja, una base) el input exacto que usaste junto con el output. Te va a ahorrar horas de debugging cuando alguien te pregunte "por qué esto salió así".
Error 5: no versionar el prompt
Este es el que más duele cuando pasa. El prompt original funcionaba bien. Alguien lo retoca "para mejorarlo", lo deploya, y tres días después el equipo se queja de que los resultados cambiaron. Nadie sabe qué versión estaba corriendo cuando las cosas iban bien y no hay forma de volver atrás.
Los prompts son código. Tenelos en el repositorio, versionalos con git, dejalos escrito en comentarios qué cambió entre versiones y por qué. Si tu equipo no los pone en git, al menos armá una hoja de Sheets (sí, irónico) que los registre con fecha y descripción. Cualquier cosa que te permita auditar.
Como bonus, cuando tengas más de tres prompts relacionados, empezá a versionar con tags semver chiquitos. extractor-facturas@1.3.0. Cuando debuggees una respuesta rara vas a saber exactamente qué versión la generó.
El patrón detrás de los cinco errores
Si mirás estos errores juntos, todos tienen algo en común: confían implícitamente en que el mundo se va a portar bien. El modelo va a devolver JSON, la hoja va a mantener su estructura, los límites no se van a tocar, los datos van a estar limpios, el prompt no va a cambiar.
La integración robusta asume lo contrario. Asume que el modelo a veces devuelve basura, que alguien va a renombrar la hoja, que el rate limit te va a pegar, que los datos vienen sucios, que los prompts evolucionan. Y deja puntos de validación, logs, y rutas de recuperación en cada uno de esos lugares.
Si estás armando una integración Sheets + LLM y querés que la auditemos antes de que rompa, o si ya se rompió y querés que entendamos por qué, contactanos.