HubSpot Rate Limit Survival

HubSpot Rate Limit Survival

Overview

Rate-limit your HubSpot integration so it survives production volume without burning the portal's daily quota before lunch. This skill covers the six failure modes that take down integrations at scale and gives you the code to prevent each one.

Key invariant: HubSpot rate limits are portal-scoped, not app-scoped. Every private app and OAuth app in the same portal shares the same daily and per-10s buckets. There is no per-app isolation.

The six production failures this skill prevents:

1. Daily quota burnout — a naive sync of 5M contacts at 100 records/call requires 50,000 API calls. A misconfigured parallel worker pool exhausts the 500K/day quota in under 90 minutes, leaving the portal dark for 22 hours.
2. Burst limit ignorance — parallelizing 20 concurrent requests saturates the 100 req/10s window instantly. The 429 retry storm then burns the daily budget too. The burst limit and daily quota are two independent counters.
3. Ignoring batch APIs — GET /contacts/{id} costs 1 quota unit and returns 1 record. POST /contacts/batch/read with 100 IDs costs 1 unit and returns 100 records. Single-record reads waste 99% of available throughput.
4. Retry-After ignored — a 429 includes Retry-After: N. Backing off by 1s when N=30 produces 29 consecutive failures. Backing off by 30s when N=1 adds unnecessary latency. Always parse and honor the header exactly.
5. Daily limit vs per-10s confusion — these are two independent systems. Burning the burst window does not decrement the daily counter. Exhausting the daily counter does not care about the per-10s rate. Conflating them breaks rate-limit logic.
6. Operations Hub Enterprise gating — the 100 req/s sustained rate is gated on Ops Hub Enterprise. A Starter account assuming that throughput gets 429s at 10x the expected rate with no clear signal that the limit tier is wrong.

Prerequisites

• Node.js 18+ or Python 3.10+
• HubSpot private app token or OAuth access token
• @hubspot/api-client (npm) or hubspot (pip) for SDK-based integrations
• For queue-based architecture: Redis 6+ with bullmq (npm) or celery+redis-py (Python)
• Portal Settings → Integrations → Private Apps to confirm the plan tier

Auth: Every API call requires Authorization: Bearer {token}. For token acquisition and caching, see hubspot-auth skill. This skill assumes a valid token is already available.

Instructions

Build in this order. Steps 1–3 are mandatory. Steps 4–6 apply when volume exceeds ~50,000 calls/day or when multiple apps share the portal.

Step 1: Read rate-limit headers on every response

Every HubSpot response carries both bucket states. Never fly blind.

interface RateLimitState {
  dailyLimit: number;
  dailyRemaining: number;
  windowMs: number;