How to Fix HubSpot API Rate Limit and Timeout Errors (429 Too Many Requests)
Resolve HubSpot API rate limit (429) and timeout errors. Learn how to implement exponential backoff, optimize batch requests, and monitor your API usage limits.
- HubSpot API enforces limits of 100-150 requests per 10 seconds (depending on authentication type) and a daily limit.
- HTTP 429 Too Many Requests indicates you've hit the rate limit; API timeouts often mean complex queries or unoptimized batching.
- Quick fix: Implement exponential backoff with retry logic and utilize HubSpot's batch/bulk API endpoints to reduce total requests.
| Method | When to Use | Time | Risk |
|---|---|---|---|
| Exponential Backoff | Immediate fix for 429 errors | Low | Low |
| Batching Requests | High volume data syncs | Medium | Low |
| Webhooks | Real-time updates instead of polling | High | Medium |
| Upgrading HubSpot Tier | Sustained high daily usage | Low | High (Cost) |
Understanding the Error
When integrating with the HubSpot API, encountering rate limits and timeouts is a common hurdle as your application scales. The most frequent error is the HTTP 429 Too Many Requests status code. This means your application is making more API calls than your HubSpot subscription or authentication method allows within a specific time window.
HubSpot enforces two primary types of rate limits:
- Burstly/Secondly Limits: Typically 100 or 150 requests per 10 seconds, depending on whether you are using an OAuth token or a Private App token.
- Daily Limits: Ranging from 250,000 to 1,000,000 API calls per day, based on your HubSpot subscription tier (Starter, Professional, or Enterprise) and API add-ons.
Conversely, HubSpot API timeouts (usually 502 Bad Gateway or 504 Gateway Timeout) happen when a single request takes too long to process. This is often caused by requesting too much data at once, using highly complex filters on search endpoints, or system degradation on HubSpot's end.
Step 1: Diagnose the Problem
The first step is to identify which limit you are hitting. You can do this by examining the HTTP response headers returned by HubSpot. HubSpot includes specific headers that detail your current usage:
X-HubSpot-RateLimit-Daily: Your total daily allowance.X-HubSpot-RateLimit-Daily-Remaining: How many requests you have left for the day.X-HubSpot-RateLimit-Secondly: Your per-second allowance.X-HubSpot-RateLimit-Secondly-Remaining: How many requests you have left in the current 10-second window.
If you are receiving timeouts, analyze the query execution time. Are you trying to pull 10,000 contacts in a single non-paginated request? Are you using complex, multi-layered search filters?
Step 2: Implement Exponential Backoff
When you receive a 429 error, your application must not immediately retry the request. Doing so will only exacerbate the problem and ensure the retry also fails. Instead, implement exponential backoff. This technique pauses execution for a short period before retrying, increasing the pause duration with each subsequent failure.
Step 3: Optimize with Batch Endpoints
If you are hitting rate limits frequently, you are likely making individual API calls in a loop. For example, updating 100 contacts one by one consumes 100 API calls. By utilizing HubSpot's Batch API endpoints (e.g., /crm/v3/objects/contacts/batch/update), you can update up to 100 contacts in a single API call. This drastically reduces your API footprint and improves synchronization speed.
Step 4: Address API Timeouts
To fix timeouts, you must reduce the payload size or complexity of your requests:
- Pagination: Always use
limitandaftercursors to paginate through large datasets. Never attempt to fetch thousands of records simultaneously. - Narrow Search Filters: Optimize the CRM Search API queries. Avoid using
CONTAINS_TOKENon large text fields if an exact match filter will suffice. - Select Specific Properties: By default, HubSpot returns a standard set of properties. Use the
propertiesquery parameter to request only the data you actually need (e.g.,?properties=firstname,email). This reduces payload size and processing time.
Frequently Asked Questions
import requests
import time
def hubspot_api_request_with_retry(url, headers, max_retries=5):
retries = 0
backoff_factor = 1.5
while retries < max_retries:
response = requests.get(url, headers=headers)
if response.status_code == 200:
return response.json()
elif response.status_code == 429:
# Rate limit hit, apply exponential backoff
wait_time = backoff_factor ** retries
print(f"Rate limit hit (429). Waiting {wait_time:.2f} seconds before retrying...")
time.sleep(wait_time)
retries += 1
elif response.status_code in [502, 504]:
# Timeout or Bad Gateway, also retry but maybe longer
wait_time = (backoff_factor ** retries) * 2
print(f"Timeout ({response.status_code}). Waiting {wait_time:.2f} seconds...")
time.sleep(wait_time)
retries += 1
else:
# Other errors, fail immediately
response.raise_for_status()
raise Exception("Max retries exceeded for HubSpot API request.")
# Example Usage:
# headers = {'Authorization': 'Bearer YOUR_PRIVATE_APP_TOKEN'}
# data = hubspot_api_request_with_retry('https://api.hubapi.com/crm/v3/objects/contacts', headers)Error Medic Editorial
Error Medic Editorial is a team of Senior DevOps and Reliability Engineers dedicated to solving complex integration, scaling, and infrastructure challenges.