n8n-nodes-hubspot-ratelimit

A custom n8n HTTP Request node with optional HubSpot rate limiting. Works exactly like the standard n8n HTTP Request node, but can automatically monitor HubSpot's rate limit headers and delay requests to prevent hitting API limits.

Features

• 🌐 Full HTTP Request Node: Complete implementation of n8n's HTTP Request node functionality
• 🚦 Optional Rate Limiting: Enable HubSpot rate limit monitoring with a checkbox (enabled by default)
• 🔒 Parallel Execution Safe: Global request queue prevents bursts from simultaneous workflow triggers
• ⏱️ Aggressive Pacing: 150ms minimum delay between requests to handle rolling window limits
• 📊 Smart Detection: Automatically reads X-HubSpot-RateLimit-* headers from responses
• 🔄 Automatic Retry: Handles 429 errors with Retry-After header support (up to 50 retries)
• ⚙️ Standard Options: Batching, SSL, redirects, pagination, proxy, timeout - all included
• 🔑 Flexible Auth: Supports Bearer, Basic, OAuth1, OAuth2, Header, Query, Digest auth
• 📤 Response headers in output: Every item includes a headers object with the HTTP response headers (e.g. x-hubspot-ratelimit-remaining)

Output

Each item from the node has:

• Response body at the top level (e.g. id, properties, etc. for HubSpot APIs)
• headers – object with all response headers as key/value strings (e.g. headers['x-hubspot-ratelimit-remaining'])

Example (HubSpot contact):

{
  "id": "12345",
  "properties": { "email": "[email protected]" },
  "headers": {
    "content-type": "application/json",
    "x-hubspot-ratelimit-remaining": "189",
    "x-hubspot-ratelimit-max": "190"
  }
}

Installation

From npm (after publishing)

# Use the directory n8n loads custom nodes from (default: ~/.n8n/nodes or ~/.n8n/custom)
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install n8n-nodes-hubspot-ratelimit

Local Development

# Clone the repository
git clone https://github.com/your-username/n8n-nodes-hubspot-ratelimit.git
cd n8n-nodes-hubspot-ratelimit

# Install dependencies
npm install

# Build the node
npm run build

# Link to your local n8n installation
npm link
mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes
npm link n8n-nodes-hubspot-ratelimit

# Restart n8n so it picks up the node

Important: Restart n8n after installing or updating the package so the node type is registered.

Usage

As a Standard HTTP Request Node

Use it like any HTTP Request node:

1. Select HTTP method (GET, POST, PUT, etc.)
2. Enter URL
3. Configure authentication (if needed)
4. Add query parameters, headers, body as needed
5. Configure standard options (batching, redirects, pagination, etc.)

With HubSpot Rate Limiting

To enable rate limiting for HubSpot API calls:

1. Check "Enable HubSpot Rate Limiting" (enabled by default)
2. Configure rate limit options:
   • Rate Limit Threshold (%): Start delaying when remaining calls drop below this % (default: 20%)
   • Max Retries on 429: Maximum retry attempts for rate limit errors (default: 50)

The node will automatically:

• Queue ALL requests globally across parallel workflow executions (prevents simultaneous bursts)
• Enforce 150ms minimum delay between requests (prevents bursts that trigger rolling window limits)
• Monitor X-HubSpot-RateLimit-* headers from responses
• Delay requests when approaching limits
• Retry with Retry-After header support on 429 errors (defaults to 10s if header missing)
• Track rate limit state across all requests

🔥 Parallel Execution Safe: When 10-20 workflows trigger simultaneously, all requests are queued and executed one-at-a-time to prevent rate limit bursts.

Configuration

Authentication Options

• None: No authentication
• Predefined Credential Type: Use existing n8n credential types (recommended)
  • Supports all n8n built-in and community credentials
  • Includes OAuth1, OAuth2, and credentials with authenticate property
• Generic Credential Type: Fully customizable authentication
  • Basic Auth
  • Bearer Token (Header Auth)
  • Custom Auth
  • Header Auth
  • Query Auth
  • Digest Auth
  • OAuth1 API
  • OAuth2 API

Standard Options

All standard n8n HTTP Request options are supported:

| Option | Description | |--------|-------------| | Batching | Split requests into batches with configurable intervals | | Ignore SSL Issues | Skip SSL certificate validation | | Lowercase Headers | Automatically lowercase header names | | Redirects | Follow redirects with max redirect limit | | Pagination | Support for paginated APIs (update parameter or next URL) | | Response | Full response, never error, response format options | | Proxy | HTTP proxy configuration | | Timeout | Request timeout in milliseconds |

Rate Limit Options (when enabled)

| Option | Default | Description | |--------|---------|-------------| | Threshold % | 20 | Start delaying when remaining calls drop below this % of limit | | Max Retries on 429 | 50 | Maximum retry attempts for 429 errors (uses Retry-After header) |

How Rate Limiting Works

When enabled, the node uses aggressive pacing to prevent 429 errors:

1. Before each request:
   • Enforces 150ms minimum delay between requests (prevents bursts)
   • Checks if remaining calls are below threshold
2. If below threshold: Waits until the rolling window resets
3. After each response: Parses X-HubSpot-RateLimit-* headers and updates state
4. On 429 error:
   • Updates rate limit state from error response
   • Waits for time specified in Retry-After header (or 10s default)
   • Retries up to 50 times before failing

Why 150ms delay? HubSpot's TEN_SECONDLY_ROLLING limit means ANY 190 requests in ANY 10-second window. A conservative 150ms delay ensures you never burst too many requests.

Parallel Execution Handling

Critical Feature: When multiple n8n workflows trigger at the same time (e.g., 10 webhooks hit simultaneously), all HubSpot API requests are queued and executed one-at-a-time across ALL parallel executions.

How It Works

Workflow 1 (10 items) starts → 10 requests queued
Workflow 2 (5 items) starts  → 5 more requests queued
Workflow 3 (8 items) starts  → 8 more requests queued

Total: 23 requests in queue, processed sequentially with 150ms delays
Time: ~3.5 seconds (instead of simultaneous burst causing 429)

What You'll See in Logs

[HubSpot Queue] Request queued. Position: 5, Queue size: 4
[HubSpot Queue] Processing request. 3 requests waiting in queue.
[HubSpot] Before request 1: 189/190 interval remaining
[HubSpot Rate Limit] Enforcing minimum delay: 188/190 remaining. Waiting 150ms

Without this queue: 10 parallel workflows = 10 simultaneous requests = instant 429 error
With this queue: 10 parallel workflows = 10 sequential requests = no 429 errors ✅

HubSpot Rate Limit Headers

The node monitors these response headers:

• X-HubSpot-RateLimit-Daily: Total daily limit
• X-HubSpot-RateLimit-Daily-Remaining: Remaining daily requests
• X-HubSpot-RateLimit-Interval-Milliseconds: Interval window (typically 10000ms)
• X-HubSpot-RateLimit-Max: Max requests per interval
• X-HubSpot-RateLimit-Remaining: Remaining requests in current interval

HubSpot Rate Limits

| App Type | Burst Limit | Daily Limit | |----------|-------------|-------------| | Private Apps (Free/Starter) | 100 per 10 seconds | 250,000 per account | | Private Apps (Professional) | 190 per 10 seconds | 625,000 per account | | Private Apps (Enterprise) | 190 per 10 seconds | 1,000,000 per account | | Public OAuth Apps | 110 per 10 seconds | Varies by account |

Example: HubSpot Contact Search with Rate Limiting

Method: POST
URL: https://api.hubapi.com/crm/v3/objects/contacts/search
Authentication: Generic Credential Type > Bearer Token
Enable HubSpot Rate Limiting: ✓

Body (JSON):
{
  "filterGroups": [{
    "filters": [{
      "propertyName": "email",
      "operator": "CONTAINS",
      "value": "@example.com"
    }]
  }],
  "properties": ["firstname", "lastname", "email"]
}

Rate Limit Options:
- Enabled: ✓ (enabled by default)
- Threshold: 20%
- Max Retries: 50

The node will automatically monitor rate limits and delay requests if needed.

Troubleshooting

"Unrecognized node type: n8n-nodes-hubspot-ratelimit.hubSpot"

This error means n8n cannot find the node. Fix it by:

1. Install in the right place
   n8n loads community nodes from:

   • ~/.n8n/nodes (recommended for npm packages)
   • ~/.n8n/custom
   • Paths set in N8N_CUSTOM_EXTENSIONS environment variable

2. Restart n8n
   Restart the n8n process after installing or linking the package

3. Docker / separate workers
   Ensure the same custom nodes directory is available where execution runs

4. Rebuild after code changes
   Run npm run build after changes, then restart n8n

Development

# Watch mode for development
npm run dev

# Lint code
npm run lint

# Format code
npm run format

# Build
npm run build

License

MIT

Credits

Built by the community for the n8n community. This node replicates the standard n8n HTTP Request node functionality while adding intelligent rate limiting specifically for HubSpot APIs.