Quando a API rejeita um token de sincronização incremental, repetir a mesma consulta pode manter uma cópia local desatualizada. Primeiro descubra se o erro é do token que marca o estado das mudanças ou da autenticação. Só depois reconstrua o espelho conforme o contrato do fornecedor e volte a acionar outros sistemas.
Resposta curta
Na API do Google Agenda, um 410 em uma consulta incremental pode indicar syncToken inválido. A documentação pede uma nova sincronização completa e substituição do estado local. O Microsoft Graph também prevê reset de consulta delta, inclusive 410 Gone ou erro de token expirado. Isso não é a mesma coisa que renovar um token OAuth. Antes de enviar lembretes, remover registros ou atualizar o CRM a partir da cópia, conclua a carga e reconcilie IDs, exclusões e alterações.
Protocolo em quatro etapas para o espelho
| Fase | Ação | Condição para avançar |
|---|---|---|
| 1. Conter | Pause efeitos baseados no espelho; registre provedor, coleção, erro e último checkpoint sem guardar o token em texto aberto | O erro foi identificado como token de estado, não de autenticação |
| 2. Reconstruir | Preserve uma evidência limitada do estado local; faça leitura completa em cópia de trabalho, cobrindo todas as páginas | A fonte retornou o marcador de conclusão, como nextSyncToken ou deltaLink |
| 3. Conciliar | Compare IDs e estados; trate exclusões e entradas restauradas conforme o provedor | Diferenças materiais têm explicação ou responsável |
| 4. Liberar | Substitua o espelho local conforme o método da integração e só então retome efeitos | Teste de amostra e contagem de controle coerentes |
Esta tabela é uma síntese operacional da Pulse, não uma sequência executada pela equipe nem uma instrução para apagar dados do fornecedor. “Limpar armazenamento do cliente” na documentação Google refere-se à cópia do aplicativo: não exclua eventos da agenda de origem. Se o espelho contém notas próprias, preserve-as separadamente antes de reconstruir.
O que conferir no retorno
O Google informa que nextSyncToken aparece apenas na última página da carga inicial. Durante atualização incremental paginada, mantenha os parâmetros compatíveis e percorra as páginas até receber o novo token. O Graph diferencia @odata.nextLink de @odata.deltaLink, admite mudanças repetidas e representa remoções com @removed nos recursos compatíveis. Não trate a primeira página nem a ausência temporária de uma entrada como prova de exclusão.
Em uma pequena clínica brasileira, por exemplo, um espelho de compromissos alimenta lembretes. Se a atualização incremental falha, a equipe suspende os lembretes baseados naquele espelho, reconstrói a cópia local e compara os IDs antes de reativar o fluxo. O exemplo é ilustrativo; não afirma integração testada, regra de prontuário nem política de retenção.
Quando interromper e pedir revisão humana
Pare se não souber qual coleção o token representa, se a carga completa não terminar, se os parâmetros mudaram, se exclusões não puderem ser distinguidas de falhas de leitura ou se o espelho guarda dados próprios que seriam perdidos. Não use o mesmo procedimento para erro 401 de acesso; verifique a conexão nesse caso. Para a nova carga, confira todas as páginas. Se o fluxo já deixou registros de fora, rastreie a lacuna.