Detén al primer error de esquema

El trabajo de implementación empezó a producir errores repetidos de invalid_json e invalid_schema. Las respuestas tentadoras estaban a un clic de distancia: reintentar la llamada, partir la tarea, subir el límite de tokens.

Ninguna ocurrió. La unidad de trabajo se detuvo al primer error. Este post va de por qué esa parada es el movimiento más fuerte cuando orquestas modelos — y de las condiciones en que no lo es.

El incidente

El pipeline: un planificador delegando trabajo de implementación acotado a subagentes, cada tarea con un brief autocontenido, un modelo fijado por rol y una lista exacta de archivos permitidos. El proveedor era experimental y el trabajo era real: implementación multiarchivo, el tipo de tarea donde una respuesta malformada no es un caso borde sino una condición recurrente de la iteración.

Bajo esa carga, los errores se repitieron: invalid_json e invalid_schema, una y otra vez, incluso después de reducir el alcance de las tareas. El riesgo que dejé asentado en su momento: auto-reintentar, subdividir el trabajo o subir max_tokens enmascararía la causa y gastaría presupuesto mientras degrada la calidad de la verificación.

Vale la pena detenerse en esa frase, “degrada la calidad de la verificación”, porque no es obvia.

Por qué el reintento es la respuesta equivocada de primera línea

Un error de esquema no es un volado. Es una señal sobre el ajuste tarea-modelo.

Cuando un modelo devuelve salida malformada para una tarea, las causas más comunes son estructurales: el brief desborda lo que el modelo puede sostener de forma coherente, la forma de la tarea no calza con las fortalezas del modelo, o la carga vive en la capa equivocada de tu pipeline. Un reintento automático mantiene la petición exactamente igual — mismo brief, misma forma, mismo modelo — y le pide un resultado distinto de todos modos. A veces lo consigue. Un parseo con suerte es peor que una falla limpia, porque cierra el incidente dejando la causa intacta.

El lado del presupuesto es igual de real. Cada reintento se paga, y bajo carga sostenida los reintentos se acumulan en una segunda factura junto al trabajo que querías comprar.

Y hay un tercer costo, más silencioso que los otros dos: los reintentos entierran la evidencia. El registro de fallas que te diría que el brief es demasiado grande, o que la tarea está en la capa equivocada, queda sobrescrito por el resultado del siguiente intento. Diagnosticar la primera falla te deja el pipeline arreglado. Reintentarla hasta que desaparezca te renta un éxito temporal al precio de no saber nada.

La parada, operacionalizada

La regla documentada de ese pipeline, casi textual: detén la unidad al primer error de esquema o parseo. Reintentar, subdividir y los cambios de límite de tokens no son respuestas de primera línea ante salida malformada.

En ese pipeline, la parada fue concreta, no un encogimiento de hombros:

La unidad se detuvo al primer error. Sin reintento automático, sin subdivisión, sin ajuste de max_tokens.
El error se preservó: el protocolo documentado registra finish_reason, usage y una muestra sanitizada de la respuesta cuando el proveedor los entrega — y lo reporta literalmente cuando no.
El brief se reabrió con la falla visible. El siguiente movimiento es una decisión humana: reescribir el brief, re-acotar la unidad, cambiar de modelo, o aprobar un experimento controlado.

Una frontera merece línea propia: una parada no es lo mismo que una prohibición de reintentar. Un reintento único como experimento deliberado y aprobado por un humano es legítimo — el protocolo permite un cambio de max_tokens exactamente así. Lo que la regla elimina es el reintento automático: el ciclo que se dispara sin diagnóstico, cuyo éxito borraría la falla que acaba de tapar. Si un reintento manual funciona, regístralo como un experimento cuyo resultado no prueba causalidad, y deja intacta la regla de parada.

La regla general

Cualquiera que orqueste modelos puede usar esto. La primera línea de defensa ante salida malformada no es un ciclo de reintentos; es una condición de paro.

Trata los errores de esquema y parseo como condiciones de paro de la unidad de trabajo, no como transitorios que aguantar.
Preserva el error: finish reason, usage, muestra sanitizada de la respuesta. La falla es dato.
Escala a un humano con la falla visible. Los movimientos correctivos — reescribir el brief, re-acotar, cambiar de modelo — son decisiones humanas, porque cambian la forma del trabajo.
Antes de que arranque la siguiente unidad de trabajo, asegúrate de que la condición de falla esté atendida. Si no, la parada no te compró nada.

El patrón detrás de la regla: un reintento automático optimiza por cerrar el incidente; una parada optimiza por entenderlo. Los sistemas de orquestación que sobreviven son los que entienden sus fallas.

Cuándo no aplica esta regla

La regla de parada gana su lugar donde las fallas se repiten. Otros regímenes:

Para un transporte inestable — timeouts, resets de conexión, 5xx de un gateway — un reintento acotado con backoff es práctica estándar y correcta. La regla de parada es para salida malformada, no para clima de red. (Un timeout de gateway sí apareció en ese pipeline, como clase de error propia, y también detenía la unidad — para flujos de grado orquestación, parar también en errores de infraestructura es la lectura más estricta y defendible.)
Si nunca has visto la falla, un reintento manual con registro completo es una sonda legítima. La regla apunta al segundo intento sin examinar, no a la primera falla observada.
Si tu sistema es una llamada única de chat para usuarios, un ciclo de recuperación estilo “responde con JSON válido, por favor” está bien. Nadie necesita un protocolo de incidentes para renderizar una burbuja de chat.

Y un límite honesto que viene de la propia fuente: esta evidencia viene de las bitácoras documentadas de un pipeline. La regla es una decisión de diseño validada en uso, no una comparativa de rendimiento. Mide tus propias tasas de parada antes de tratar los números como universales.

Epílogo

El proveedor experimental detrás de esos errores terminó eliminado, y los documentos del protocolo quedan como referencia histórica. La corrección le sobrevivió al proveedor: detén al primer error de esquema, preserva la evidencia, y pon el siguiente movimiento en manos humanas.

Este incidente está documentado, con su corrección y su regla aprendida, en el expediente de Sistemas de agentes. Su pareja, en la dirección contraria de la misma lección — probar que el trabajo ocurrió antes de creerle a una luz verde — es Agente READY, uso 0%.