HubSpot OAuth BAD_REFRESH_TOKEN — What it means & how to fix it

Encountering the "BAD_REFRESH_TOKEN" error when integrating with HubSpot’s APIs using OAuth indicates a missing or invalid refresh token, which can arise from various reasons including user actions like revoking access or uninstalling an app, reaching access token limits, token expiration, scope changes, or mismatched client credentials. The error is final, meaning revoked tokens cannot be revived, and users must re-authenticate to obtain a new token. To minimize disruptions, it’s advised to refresh tokens regularly, discard stale tokens, monitor for error spikes, and handle app uninstallation and errors gracefully. Adopting engineering practices such as scheduled refreshes and using tools like Nango for automated token management can prevent issues and maintain smooth API operations.