Invalid refresh token na HubSpot: causas e como corrigir

O erro de "invalid refresh token" da HubSpot (BAD_REFRESH_TOKEN / invalid_grant) significa que a HubSpot revogou permanentemente ou não reconhece mais o seu refresh token de OAuth, geralmente porque o usuário desinstalou o app, o acesso foi revogado, as credenciais do seu cliente não batem ou o seu app armazenou um token desatualizado. O token não pode ser revivido. A única correção é mandar o usuário de volta pelo fluxo de autorização OAuth para emitir um novo. A prevenção vem de armazenamento atômico de tokens, lock distribuído nos refreshes, webhooks de desinstalação e monitoramento da taxa de falha de refresh.

Sua integração com a HubSpot rodou bem por meses, e então toda chamada de API começa a falhar com um erro 400 e a mensagem refresh token is invalid, expired or revoked. O trabalho de verdade é entender por que aconteceu e construir a integração para degradar com elegância quando acontecer de novo. Este guia cobre o que invalida refresh tokens da HubSpot, como diagnosticar e se recuperar do erro, e as práticas de produção que previnem a maioria das ocorrências.

Principais pontos

• Os access tokens da HubSpot expiram a cada 30 minutos; os refresh tokens nunca expiram por cronograma, eles só morrem quando algo os revoga.
• BAD_REFRESH_TOKEN é terminal: repetir a chamada com o mesmo token nunca vai funcionar, e não existe API para restaurá-lo.
• A causa mais comum é a desinstalação do app ou a revogação manual; as causas mais comuns autoinfligidas são credenciais trocadas e condições de corrida que sobrescrevem o token atual.
• Recuperação = rodar de novo o fluxo de autorização OAuth. Transforme a reconexão em um recurso de um clique no produto, não em um ticket de suporte.
• Cerca de 1% das conexões OAuth se perde por mês na média do setor: trate a revogação ocasional como normal e desenhe para ela.
• Migre para os endpoints OAuth 2026-03 da HubSpot; a API OAuth v1 tem aposentadoria marcada para 16 de fevereiro de 2027.

Como é o erro de invalid refresh token da HubSpot?

Quando você chama o endpoint de token da HubSpot (POST /oauth/v1/token, ou POST /oauth/2026-03/token na versão mais recente da API) com uma requisição grant_type=refresh_token e o token não é mais válido, a HubSpot retorna um HTTP 400 com um corpo assim:

{   "status": "BAD_REFRESH_TOKEN",   "message": "refresh token is invalid, expired or revoked",   "error": "invalid_grant" }

Duas coisas importam aqui. Primeiro, invalid_grant é o erro padrão de OAuth da RFC 6749: não é uma falha transitória, e repetir com o mesmo token nunca vai funcionar. Segundo, o próprio guia de tokens OAuth da HubSpot confirma que o token está terminalmente morto: inválido, expirado ou revogado levam todos ao mesmo caminho de recuperação.

Uma recapitulada rápida no modelo de tokens: os access tokens da HubSpot expiram 30 minutos depois de emitidos (uma mudança anunciada pela HubSpot que reduziu a vida útil antiga de 6 horas), enquanto os refresh tokens são de longa duração e não têm expiração programada. Então, quando um refresh token morre, é quase sempre porque algo o revogou, não porque venceu no calendário. Os fundamentos desse modelo estão no nosso guia de autenticação e apps na API da HubSpot.

O que causa um refresh token inválido na HubSpot? (7 causas)

Num relance: as causas, como detectá-las e a correção:

1. O usuário desinstalou o seu app

A causa mais comum, de longe. Quando um usuário da HubSpot desinstala o seu app em Configurações → Integrações → Connected Apps, a HubSpot invalida imediatamente o refresh token daquela instalação. Nada mudou do seu lado; a autorização em si é que se foi.

2. O acesso foi revogado manualmente

Administradores podem revogar o acesso de um app sem uma desinstalação completa, e mudanças de super admin ou de usuário no portal (um usuário desativado, um assento removido no caso de tokens no nível do usuário) podem ter o mesmo efeito. Da perspectiva da sua integração, é idêntico a uma desinstalação.

3. Client ID ou client secret errados

Um refresh token é vinculado ao app que o emitiu. Se a sua requisição de refresh carrega um client_id ou client_secret diferente (um secret rotacionado, uma credencial de staging apontada para tokens de produção, ou dois apps compartilhando um mesmo armazenamento de tokens), a HubSpot a rejeita como refresh token ruim mesmo com o token em si estando bom. É a primeira coisa a checar quando os erros aparecem logo depois de um deploy ou de uma rotação de credenciais.

4. Você perdeu o token atual em uma condição de corrida

Se múltiplos servidores ou workers fazem refresh de tokens da mesma instalação ao mesmo tempo, um processo pode persistir um token enquanto outro o sobrescreve com dados velhos. Seu banco acaba guardando um token que não corresponde mais ao que a HubSpot espera. Erros intermitentes de BAD_REFRESH_TOKEN sem nenhuma ação do usuário, como os relatados em threads da comunidade da HubSpot, são com frequência esse modo de falha, e não a HubSpot revogando tokens aleatoriamente.

5. Mudanças de escopo que exigem reautorização

Se você muda os escopos que o app solicita depois de os usuários já o terem instalado, as autorizações existentes podem deixar de corresponder. Os usuários precisam passar de novo pela autorização para consentir com os novos escopos, e os tokens antigos ligados ao conjunto anterior podem ser invalidados no processo. Se o sintoma for 403 nas chamadas em vez de erro no refresh, o caminho é o nosso guia do erro de escopos na API da HubSpot.

6. Requisições de refresh malformadas

O endpoint de token espera Content-Type: application/x-www-form-urlencoded com os parâmetros no corpo da requisição. Peculiaridades de SDK ou requisições feitas à mão que colocam parâmetros na query string, codificam o token duas vezes ou perdem um caractere no armazenamento vão parecer um token inválido. Note que os endpoints OAuth 2026-03 da HubSpot agora exigem todos os parâmetros no corpo da requisição, o que de quebra mantém o seu client_secret fora dos logs de servidor. Se você está nos endpoints v1, planeje a migração: a HubSpot anunciou que a v1 da API de OAuth será aposentada em 16 de fevereiro de 2027.

7. Revogação por segurança

Uma pequena base de revogações acontece por razões que a HubSpot não detalha: heurísticas de segurança, redefinições de senha na conta conectada e eventos parecidos. Dados de provedores de infraestrutura de OAuth colocam a perda natural de refresh tokens em cerca de 1% das conexões por mês. Sua arquitetura deve tratar a revogação ocasional como normal, não como excepcional.

Como corrigir um erro de BAD_REFRESH_TOKEN? (5 passos)

Passo 1 — Confirme que o token está morto mesmo. Reproduza a chamada de refresh fora do seu app (Postman ou curl) com o token exato armazenado e as suas credenciais de produção. Se funcionar ali, o seu bug está no formato da requisição ou na configuração de credenciais, não no token. Esse passo de isolamento é o conselho padrão nas threads de troubleshooting da comunidade da HubSpot.

Passo 2 — Verifique se o app ainda está instalado. Pergunte ao cliente (ou cheque os logs do seu webhook de desinstalação) se o app ainda aparece nos Connected Apps do portal dele. Se foi desinstalado, o token não volta: pule para o passo 4.

Passo 3 — Audite as credenciais e o armazenamento de tokens. Confirme que o par client_id/client_secret corresponde ao app que emitiu o token, e procure nos logs por tentativas de refresh concorrentes na época em que os erros começaram. Se encontrar uma corrida, corrija o lock antes de reautorizar, ou o problema volta.

Passo 4 — Rode o fluxo OAuth de novo. Mande o usuário de volta pela sua URL de instalação (https://app.hubspot.com/oauth/authorize?...). Um novo código de autorização gera um access token e um refresh token novos. Não existe atalho de API: tokens revogados não podem ser restaurados.

Passo 5 — Transforme a reconexão em recurso do produto, não em ticket de suporte. Marque a conta afetada como desconectada no seu sistema, pause o trabalho de API enfileirado para aquele portal e mostre um botão claro de "Reconectar HubSpot", com uma notificação por e-mail junto. As integrações que parecem confiáveis não são as que nunca perdem tokens; são aquelas em que a reconexão custa um clique para o usuário.

Não é desenvolvedor? A versão desse erro na caixa de e-mail

Usuários da HubSpot às vezes veem a linguagem de "invalid refresh token" quando uma caixa conectada do Gmail ou do Outlook se desconecta, geralmente depois de uma troca de senha ou de um evento de segurança do Google/Microsoft que revoga o acesso da HubSpot. A correção é o equivalente da reautorização no nível do usuário: vá em Configurações → Geral → E-mail, remova a conexão antiga e reconecte a caixa de entrada. Nenhum trabalho de API necessário.

Como prevenir refresh tokens inválidos em produção?

Você não consegue impedir usuários de desinstalar o seu app, mas consegue eliminar as causas autoinfligidas, que na nossa experiência são a maioria dos casos recorrentes.

Mantenha uma única fonte da verdade para os tokens. Um registro criptografado por instalação, indexado pelo ID do portal. Todo refresh bem-sucedido precisa atualizar atomicamente o access token e, se a HubSpot retornar um, o refresh token. Nunca deixe dois ambientes (staging/produção) ou dois serviços compartilharem escrita nas mesmas linhas de token.

Serialize os refreshes com um lock distribuído. Antes de fazer o refresh, adquira um lock por portal (o SET NX EX do Redis funciona bem, com timeout de 10 a 30 segundos). Workers concorrentes esperam e depois leem o token novo, em vez de disputar. O próprio guia da HubSpot sobre gestão de tokens OAuth em produção percorre esse padrão em detalhe.

Faça o refresh proativamente, usando o expires_in. Não fixe os 30 minutos no código: leia o expires_in da resposta do token e faça o refresh alguns minutos antes, com um refresh disparado por 401 como reserva. Vidas úteis fixadas no código foram exatamente o que quebrou integrações quando a HubSpot encurtou a expiração dos access tokens.

Assine os webhooks de desinstalação. Quando um portal desinstala o seu app, marque a instalação como morta na hora, em vez de descobrir por uma parede de chamadas de API falhando. Se você constrói sobre webhooks, nosso guia de webhooks da HubSpot, com assinaturas, idempotência e dead-letter, cobre como deixar esses handlers seguros para produção.

Monitore falhas de refresh como métrica de primeira classe. Acompanhe a taxa de sucesso de refresh por app e alerte quando as falhas passarem de um limiar pequeno; o guia de gestão de tokens OAuth da própria HubSpot lista uma taxa de falha de refresh acima de 5% como gatilho de alerta. Um pico geralmente significa que uma rotação de credencial deu errado ou que uma corrida foi introduzida, e pegar isso em minutos em vez de dias é a diferença entre uma reconexão e centenas.

Trate o erro onde você chama a API. Todo caminho de chamada à API da HubSpot, incluindo as custom code actions em workflows, onde o manejo de tokens tem restrições próprias, deve distinguir invalid_grant (parar, marcar como desconectado, pedir reautorização) de 429/5xx (recuar e tentar de novo). Repetir um refresh token morto só queima rate limit e suja os seus logs.

Por que isso importa além da mensagem de erro

Um refresh token inválido raramente é só um incômodo de engenharia. Se a sua integração com a HubSpot alimenta roteamento, relatórios ou automação, um portal silenciosamente desconectado significa leads perdidos e dashboards defasados: um problema de operação de receita vestindo a roupa de um erro de desenvolvedor. Tratar a saúde das integrações como parte da sua disciplina de Revenue Operations, com métricas e alertas com dono, é o que impede uma reconexão de um clique de virar uma crise de dados no fechamento do trimestre.

Perguntas frequentes

O que significa "refresh token is invalid, expired or revoked" na HubSpot?

Significa que a HubSpot não reconhece mais o refresh token que o seu app apresentou, na maioria das vezes porque o usuário desinstalou o app ou revogou o acesso, as suas credenciais não correspondem ao app emissor ou o token armazenado está desatualizado. O token não pode ser reativado; o usuário precisa reautorizar o seu app.

Refresh tokens da HubSpot expiram?

Não por cronograma. Os access tokens da HubSpot expiram 30 minutos depois de emitidos, mas os refresh tokens permanecem válidos indefinidamente até que algo os revogue: desinstalação do app, revogação manual, mudanças de escopo ou eventos de segurança na conta conectada.

Como corrijo um erro de BAD_REFRESH_TOKEN?

Primeiro verifique a falha com uma requisição direta via Postman/curl usando o token exato armazenado e o client_id/client_secret de produção. Se o token estiver de fato revogado, redirecione o usuário pela sua URL de instalação OAuth para gerar tokens novos e atualize o seu armazenamento. Não existe endpoint para restaurar um refresh token revogado.

Por que meu refresh token fica inválido se ninguém desinstalou o app?

Os suspeitos de sempre são uma condição de corrida (refreshes concorrentes sobrescrevendo os tokens uns dos outros), credenciais de cliente trocadas ou rotacionadas, ou uma requisição de refresh malformada. Uma pequena porcentagem de tokens também é revogada por eventos de segurança, como redefinições de senha; cerca de 1% das conexões por mês é a perda normal.

Consigo obter um novo refresh token da HubSpot sem interação do usuário?

Não. Emitir um novo refresh token exige que o usuário complete de novo o fluxo de autorização OAuth. O melhor que você pode fazer é tornar a reautorização sem atrito: detectar o invalid_grant, pausar as sincronizações daquele portal e dar ao usuário um caminho de reconexão de um clique.

Quanto tempo duram os access tokens da HubSpot?

Os access tokens da HubSpot expiram 30 minutos depois de gerados. Sua integração deve ler o valor de expires_in de cada resposta de token e fazer o refresh proativamente alguns minutos antes da expiração, em vez de fixar a vida útil no código.

Qual a diferença entre um access token e um refresh token da HubSpot?

O access token é a credencial de curta duração (30 minutos) enviada em toda requisição de API. O refresh token é a credencial de longa duração que o seu app guarda com segurança e troca no endpoint de token da HubSpot por novos access tokens; ele nunca é enviado nas chamadas comuns de API.

Desinstalar um app da HubSpot invalida os tokens dele?

Sim. Desinstalar um app invalida imediatamente o refresh token daquela instalação. Access tokens já emitidos podem sobreviver até a expiração de 30 minutos, mas nenhum novo pode ser gerado, então a integração fica efetivamente desconectada.

Qual endpoint OAuth da HubSpot usar em 2026?

Use o endpoint versionado POST https://api.hubapi.com/oauth/2026-03/token, que exige todos os parâmetros no corpo da requisição (mantendo o client secret fora dos logs de servidor) e adiciona um endpoint de introspecção de token. A HubSpot anunciou que a API OAuth v1 legada será aposentada em 16 de fevereiro de 2027.