Qué hacer cuando tu cursor de la API de Pinnacle desaparece

La corrección para un cursor perdido de la API de Pinnacle es corta: detén el bucle delta, haz una lectura completa del tablero, guarda el nuevo cursor junto con el snapshot que produjo, y retoma el sondeo delta desde ahí. El solapamiento entre tu último estado bueno y la lectura completa lo absorbe la regla de deduplicación que ya ejecutas. Lo que importa es todo lo que rodea a esa corrección: notar la pérdida rápido y hacerla rara.

Cómo se pierden los cursores

El cursor es una posición en el feed: el valor last de la respuesta anterior, devuelto como since en la siguiente. Perderlo suele significar perder el almacén donde vivía. Un flush de Redis, un volumen descartado, un despliegue que apuntó el sondeador a una base vacía, o un proceso que cayó entre recibir una respuesta y persistir su cursor producen el mismo resultado.

Una pérdida más sutil es el cursor viejo: el valor existe pero ya no corresponde a nada que la API reconozca, así que cada llamada delta se comporta como una primera llamada. Trata ambos casos igual.

Nótalo rápido

Dos señales atrapan un problema de cursor. Al arrancar, un sondeador que no encuentra cursor almacenado debe avisar en voz alta en lugar de empezar de nuevo en silencio, porque una lectura completa silenciosa parece sana en los logs mientras multiplica tu volumen de solicitudes. En estado estacionario, la métrica de progreso del cursor vigila: alerta cuando el valor last no ha cambiado en 30 minutos mientras hay eventos en juego en el tablero, como indica la guía de monitorización de pipeline, verificado el 2026-09-30.

El procedimiento de recuperación

Ejecuta en orden:

1. Detén el bucle delta. Sondear con un cursor ausente o roto solo gasta solicitudes.
2. Haz una lectura completa del tablero por deporte y fase que cubres. El contraste documentado es 1.522 eventos para un tablero completo de fútbol prepartido contra 7 eventos cambiados en el delta posterior, exactamente por eso las lecturas completas pertenecen a la recuperación y no al estado estacionario.
3. Persiste el nuevo cursor atómicamente con el snapshot que produjo, para que el par sobreviva junto a la próxima caída.
4. Retoma el bucle delta desde ese cursor.

Tus tablas de historial sobreviven al solapamiento intactas. La regla de la guía de almacenamiento, insertar una fila solo cuando el precio de una selección difiere de la última fila que guardas, significa que la lectura completa escribe solo lo que realmente cambió mientras estabas fuera. Lo que no puedes recuperar es el camino entre el último sondeo bueno y el reinicio. La guía de almacenamiento es directa: los huecos siguen siendo huecos, así que registra la caída en una tabla separada y deja que las consultas distingan un mercado tranquilo de uno ausente.

Haz que la próxima pérdida sea aburrida

Tres hábitos convierten la pérdida de cursor de incidente en nota al pie. Persiste el cursor en la misma transacción que el estado que produjo, para no tener nunca uno sin el otro. Mantén un único escritor para el cursor, porque dos sondeadores avanzando un cursor en lugares distintos es una pérdida más lenta. Y ensaya la recuperación: la guía de integración reserva los snapshots completos para el primer arranque y la recuperación de desastres, y una recuperación que nunca has ejecutado es una recuperación que solo esperas que funcione.

Un cursor es estado barato. Trátalo como estado: guárdalo con cuidado, obsérvalo moverse, y conoce los cuatro pasos antes del día en que los necesites.