O que fazer quando seu cursor da API da Pinnacle some

A correção para um cursor perdido da API da Pinnacle é curta: pare o loop delta, faça uma leitura completa do board, armazene o novo cursor junto com o snapshot que ele produziu e retome o polling delta a partir daí. A sobreposição entre seu último estado bom e a leitura completa é absorvida pela regra de deduplicação que você já roda. O que importa é tudo ao redor dessa correção: notar a perda rápido e torná-la rara.

Como os cursores se perdem

O cursor é uma posição no feed: o valor last da resposta anterior, enviado de volta como since na próxima. Perdê-lo normalmente significa perder o armazenamento onde ele vivia. Um flush no Redis, um volume descartado, um deploy que apontou o poller para um banco vazio, ou um processo que caiu entre receber uma resposta e persistir seu cursor produzem o mesmo resultado.

Uma perda mais sutil é o cursor velho: o valor existe, mas não corresponde mais a nada que a API reconheça, então toda chamada delta se comporta como uma primeira chamada. Trate os dois casos da mesma forma.

Perceba rápido

Dois sinais pegam um problema de cursor. Na inicialização, um poller que não encontra cursor armazenado deve avisar alto em vez de recomeçar em silêncio, porque uma leitura completa silenciosa parece saudável nos logs enquanto multiplica seu volume de requisições. No estado estacionário, a métrica de progresso do cursor vigia: alerte quando o valor last não muda por 30 minutos enquanto há eventos em jogo no board, como o guia de monitoramento de pipeline afirma, verificado em 2026-09-30.

O procedimento de recuperação

Execute em ordem:

1. Pare o loop delta. Fazer polling com cursor ausente ou quebrado só gasta requisições.
2. Faça uma leitura completa do board por esporte e fase que você cobre. O contraste documentado é 1.522 eventos para um board completo de futebol pré-jogo contra 7 eventos alterados no delta seguinte, exatamente por isso leituras completas pertencem à recuperação e não ao estado estacionário.
3. Persista o novo cursor atomicamente com o snapshot que ele produziu, para que o par sobreviva junto à próxima queda.
4. Retome o loop delta a partir desse cursor.

Suas tabelas de histórico sobrevivem à sobreposição intactas. A regra do guia de armazenamento, inserir uma linha só quando o preço de uma seleção difere da última linha que você guarda, significa que a leitura completa grava apenas o que realmente mudou enquanto você estava fora. O que você não recupera é o caminho entre o último poll bom e o reinício. O guia de armazenamento é direto: lacunas continuam lacunas, então registre a queda em uma tabela separada e deixe as consultas distinguirem um mercado quieto de um ausente.

Torne a próxima perda sem graça

Três hábitos transformam a perda de cursor de incidente em nota de rodapé. Persista o cursor na mesma transação do estado que ele produziu, para nunca segurar um sem o outro. Mantenha um único escritor para o cursor, porque dois pollers avançando um cursor em lugares diferentes é uma perda mais lenta. E ensaie a recuperação: o guia de integração reserva snapshots completos para a primeira inicialização e a recuperação de desastres, e uma recuperação que você nunca rodou é uma recuperação que você só espera que funcione.

Um cursor é estado barato. Trate-o como estado: armazene com cuidado, observe-o se mover e conheça os quatro passos antes do dia em que precisar deles.