MarketingSoda
Troubleshooting & Reference

HubSpot OAuth Troubleshooting Guide

Resolve common issues when connecting your HubSpot account to MarketingSoda Refine, including permission errors, expired tokens, and rate limits.

Overview

This guide helps you resolve common issues when connecting your HubSpot account to MarketingSoda Refine™ for the free database health scan. The connection uses OAuth, an industry-standard protocol that lets you authorize MarketingSoda Refine to read your HubSpot data without sharing your password.

How the Connection Works

When you click "Connect Your HubSpot," here is what happens:

  1. You are redirected to HubSpot -- You see the official HubSpot authorization screen.
  2. You approve read-only access -- MarketingSoda Refine requests permission to read your contacts only.
  3. HubSpot sends you back -- After approval, HubSpot redirects you to MarketingSoda Refine.
  4. Your scan begins automatically -- We start reading and scoring your contacts.

The entire process takes about 30 seconds. Your HubSpot login credentials are never shared with MarketingSoda Refine.

Required HubSpot Permissions

MarketingSoda Refine requests a single, minimal permission:

PermissionWhat It Means
crm.objects.contacts.readRead-only access to your contact records

What we can do: Read contact names, emails, phone numbers, job titles, and company information.

What we cannot do: Create, edit, or delete any data in your HubSpot portal. We have no write access.

Who Can Authorize the Connection

You must be a Super Admin or have App Marketplace Access permissions in your HubSpot portal. If you see a permissions error, ask your HubSpot administrator to either:

  • Grant you the necessary permissions, or
  • Perform the connection on your behalf

Common Connection Errors

"You declined access to your HubSpot account"

What happened: You clicked "Deny" on the HubSpot authorization screen instead of "Grant access."

How to fix:

  1. Go back to the audit page.
  2. Click "Connect Your HubSpot" again.
  3. When you see the HubSpot authorization screen, click "Grant access."

Why it is safe: We only request read-only contact access and never modify your data.

"The authorization code was invalid or has expired"

What happened: There was a delay between when you approved access and when the connection was completed. Authorization codes expire after a short time.

How to fix:

  1. Return to the audit page.
  2. Click "Connect Your HubSpot" to start fresh.
  3. Complete the authorization promptly without switching tabs.

Tip: Avoid leaving the HubSpot authorization screen open for more than a few minutes.

"We were unable to complete the connection with HubSpot"

What happened: The token exchange between HubSpot and MarketingSoda Refine failed. This is usually a temporary issue on HubSpot's side.

How to fix:

  1. Wait 30 seconds.
  2. Return to the audit page.
  3. Try connecting again.

If the issue persists after 3 attempts, HubSpot may be experiencing downtime. Check HubSpot Status for any ongoing incidents.

"The authorization request was missing required information"

What happened: The connection request was interrupted, possibly due to a browser extension, VPN, or network issue.

How to fix:

  1. Disable any browser extensions that modify network requests (ad blockers, privacy tools).
  2. If using a VPN, try disconnecting temporarily.
  3. Clear your browser cookies for marketingsoda.ai.
  4. Try connecting again.

"Your session has expired"

What happened: For security, MarketingSoda Refine sessions are limited to 10 minutes. If the scan takes longer or you navigated away, your session expired.

How to fix:

  1. Return to the audit page.
  2. Click "Connect Your HubSpot" to start a new session.
  3. Stay on the scanning page until the scan completes (typically 2-5 minutes).

"HubSpot authentication failed. Please reconnect."

What happened: Your HubSpot access token expired during the scan. This can happen if your scan takes longer than expected.

How to fix:

  1. Click the "Reconnect HubSpot" button shown on the error screen.
  2. Approve access again on the HubSpot authorization screen.
  3. The scan will restart automatically.

"No active audit session. Please connect your HubSpot account."

What happened: You tried to start a scan without an active connection, or your session cookie was cleared.

How to fix:

  1. Make sure cookies are enabled for marketingsoda.ai.
  2. Return to the audit page.
  3. Click "Connect Your HubSpot" to establish a new session.

"Too many requests. Please wait before running another audit."

What happened: You attempted to run multiple scans in quick succession. MarketingSoda Refine limits scans to one per minute per user.

How to fix:

  1. Wait at least 60 seconds.
  2. Try running the scan again.

This limit protects both your HubSpot API usage and our scanning infrastructure.

Step-by-Step Reconnection Guide

If your connection is not working, follow these steps in order:

  1. Clear your browser cookies for marketingsoda.ai (this removes any stale session data).
  2. Open a fresh browser tab and navigate to marketingsoda.ai/en/audit.
  3. Click "Connect Your HubSpot" and wait for the HubSpot authorization screen.
  4. Verify you are logged into the correct HubSpot account (check the portal name in the top-right).
  5. Click "Grant access" on the authorization screen.
  6. Stay on the page -- do not close the tab or navigate away during the scan.
  7. Wait for the scan to complete (typically 2-5 minutes depending on your database size).

Rate Limiting Issues

HubSpot API Rate Limits

HubSpot enforces API rate limits that may occasionally affect your scan:

LimitDetail
Burst limit190 requests per 10 seconds
Daily limit650,000-1,000,000 requests per day (varies by plan)

MarketingSoda Refine handles rate limiting automatically by:

  • Retrying requests after the delay specified by HubSpot
  • Capping retry delays at 10 seconds
  • Limiting scans to 500 contacts maximum for the free audit

What You See When Rate Limited

The scanning progress may pause briefly (usually a few seconds). The progress bar will resume automatically. No action is needed on your part.

If Your Scan Appears Stuck

If the progress bar has not moved for more than 2 minutes:

  1. Click the "Try Again" button.
  2. If the issue persists, try again in 15-30 minutes (HubSpot rate limits reset).

Multi-Account Scenarios

Connecting the Wrong HubSpot Portal

If you have multiple HubSpot accounts and connected the wrong one:

  1. Complete or cancel the current scan.
  2. Log out of HubSpot in your browser, or switch to the correct account.
  3. Return to the audit page and connect again.
  4. Verify the portal name on the HubSpot authorization screen before approving.

Scanning Multiple Portals

You can scan different HubSpot portals one at a time. Each scan generates a separate report:

  1. Complete the scan for your first portal.
  2. Log out of that HubSpot account or switch accounts.
  3. Start a new scan from the audit page.

Note: Each report has its own unique link and is independent of other scans.

Shared HubSpot Portals

If multiple people in your organization want to run the audit, each person can connect independently. MarketingSoda Refine uses the same read-only scope regardless of who connects, so there is no risk of one person's scan affecting another.

Security and Privacy

What Data Do We Access?

We read the following contact fields during the scan:

  • First name, last name
  • Email address
  • Phone number
  • Job title
  • Company name
  • City, state, country
  • LinkedIn URL
  • Seniority and department
  • Created date and last modified date

What Data Do We Store?

  • Contact-level data: Never stored. Your individual contact records are analyzed in real-time and discarded.
  • Aggregate results only: We store your overall score, grade distribution, dimension averages, and recommendations -- no personally identifiable contact information.
  • Report expiry: Reports are retained for 12 months, then expire.

How to Revoke Access

You can revoke MarketingSoda Refine's access at any time:

  1. Log in to your HubSpot account.
  2. Go to Settings (gear icon) > Integrations > Connected Apps.
  3. Find "MarketingSoda DQ Audit" in the list.
  4. Click Uninstall or Revoke access.

Revoking access immediately prevents MarketingSoda Refine from reading any further data.

Still Need Help?

If none of the above solutions resolve your issue, contact us:

  • Email: support@marketingsoda.ai
  • Subject line: Include "OAuth" or "HubSpot connection" so we can prioritize your request.
  • Helpful details to include:
    • The error message you saw (screenshot if possible)
    • Your HubSpot plan type (Free, Starter, Professional, Enterprise)
    • Whether you have Super Admin access
    • Your browser name and version
← Back to Support