Rate Limits

Overview

Deel enforces rate limits to ensure API stability and fair usage across all integrations. Understanding and respecting these limits is essential for building reliable applications.

Each organization can make up to 5 API requests per second across all tokens.
The rate limit is shared organization-wide, regardless of how many API tokens you use.
If you exceed your rate limit, the API will return a 429 Too Many Requests error.
Rate limiting uses a rolling 1-second window that automatically resets each second.

Rate Limit Details

Current Limits

Metric	Limit
Requests per second	5
Scope	Per organization
Window	1 second (rolling)
Error code	429 Too Many Requests

Rate limits are enforced per organization, not per token. All API tokens within your organization share the same rate limit quota. If you have multiple services or processes making API calls, they all count toward the same 5 requests/second limit.

How It Works

The rate limit operates on a rolling 1-second window:

Second 1: ✅ ✅ ✅ ✅ ✅ (5 requests - OK)
Second 2: ❌ (6th request - rate limited!)
// Wait for next cycle
Second 3: ✅ ✅ ✅ ✅ ✅ (5 requests - OK again)

When you exceed 5 requests per second:

Additional requests receive a 429 status code
You must wait until the next cycle starts
The limit automatically resets each second

Handling Rate Limit Errors

Deel API does not return rate limit headers. You won’t know you’ve hit the rate limit until you receive a 429 error. This makes proactive rate limiting especially important.

When you exceed the rate limit, you’ll receive a 429 error:

1 {
2   "error": "Rate limit exceeded",
3   "status": 429,
4   "message": "Too many requests. Please wait before retrying."
5 }

Best Practice: Exponential Backoff

Implement exponential backoff when hitting rate limits:

1 async function makeRequestWithRetry(url, options, maxRetries = 3) {
2   for (let attempt = 0; attempt < maxRetries; attempt++) {
3     try {
4       const response = await fetch(url, options);
5 
6       // Success
7       if (response.ok) {
8         return await response.json();
9       }
10 
11       // Rate limited
12       if (response.status === 429) {
13         const retryAfter = response.headers.get('Retry-After') || 1;
14         const delay = Math.min(Math.pow(2, attempt) * 1000, 5000); // Max 5s
15 
16         console.log(`Rate limited. Waiting ${delay}ms before retry...`);
17         await new Promise(resolve => setTimeout(resolve, delay));
18         continue;
19       }
20 
21       // Other errors
22       throw new Error(`HTTP ${response.status}: ${response.statusText}`);
23 
24     } catch (error) {
25       if (attempt === maxRetries - 1) throw error;
26 
27       const delay = Math.pow(2, attempt) * 1000;
28       await new Promise(resolve => setTimeout(resolve, delay));
29     }
30   }
31 }

Strategies to Stay Within Limits

1. Request Queuing (Most Important)

Queue requests to ensure you never exceed 5 requests per second:

1 class RateLimitedQueue {
2   constructor(requestsPerSecond = 5) {
3     this.queue = [];
4     this.interval = 1000 / requestsPerSecond; // 200ms between requests
5     this.processing = false;
6     this.lastRequestTime = 0;
7   }
8 
9   async add(requestFn) {
10     return new Promise((resolve, reject) => {
11       this.queue.push({ requestFn, resolve, reject });
12       if (!this.processing) this.process();
13     });
14   }
15 
16   async process() {
17     this.processing = true;
18 
19     while (this.queue.length > 0) {
20       const { requestFn, resolve, reject } = this.queue.shift();
21 
22       // Ensure minimum interval between requests
23       const now = Date.now();
24       const timeSinceLastRequest = now - this.lastRequestTime;
25       if (timeSinceLastRequest < this.interval) {
26         await new Promise(r => setTimeout(r, this.interval - timeSinceLastRequest));
27       }
28 
29       try {
30         const result = await requestFn();
31         resolve(result);
32       } catch (error) {
33         reject(error);
34       }
35 
36       this.lastRequestTime = Date.now();
37     }
38 
39     this.processing = false;
40   }
41 }
42 
43 // Usage
44 const queue = new RateLimitedQueue(5); // 5 requests per second
45 
46 // Queue multiple requests
47 const results = await Promise.all([
48   queue.add(() => deelAPI.get('/contracts/1')),
49   queue.add(() => deelAPI.get('/contracts/2')),
50   queue.add(() => deelAPI.get('/contracts/3')),
51   // ... up to hundreds of requests
52 ]);

2. Batch Requests

When possible, use batch operations instead of individual requests:

1 // ❌ Inefficient - 100 individual requests
2 for (const contractId of contractIds) {
3   await getContract(contractId);
4 }
5 
6 // ✅ Efficient - Single batch request (if supported)
7 const contracts = await getContracts({ ids: contractIds });

3. Space Out Requests

Avoid bursts of requests. Spread them out over time:

1 // ❌ Bad - Burst of 20 requests at once
2 await Promise.all(
3   contractIds.map(id => getContract(id))
4 );
5 
6 // ✅ Good - Controlled rate
7 for (const id of contractIds) {
8   await getContract(id);
9   await sleep(200); // 200ms between requests = 5/second
10 }

4. Cache Responses

Reduce API calls by caching frequently accessed data:

1 const NodeCache = require('node-cache');
2 const cache = new NodeCache({ stdTTL: 300 }); // 5 minute TTL
3 
4 async function getCachedContract(contractId) {
5   // Check cache first
6   const cached = cache.get(`contract_${contractId}`);
7   if (cached) {
8     console.log('Cache hit');
9     return cached;
10   }
11 
12   // Fetch from API if not cached
13   const contract = await deelAPI.get(`/contracts/${contractId}`);
14 
15   // Store in cache
16   cache.set(`contract_${contractId}`, contract);
17 
18   return contract;
19 }

5. Centralize API Requests

Since rate limits are organization-wide, centralize request handling to avoid conflicts:

1 class CentralizedAPIClient {
2   constructor() {
3     this.queue = new RateLimitedQueue(5);
4   }
5 
6   async makeRequest(method, endpoint, data = null) {
7     return this.queue.add(async () => {
8       const options = {
9         method,
10         headers: {
11           'Authorization': `Bearer ${process.env.DEEL_API_TOKEN}`,
12           'Content-Type': 'application/json'
13         }
14       };
15 
16       if (data) {
17         options.body = JSON.stringify(data);
18       }
19 
20       const response = await fetch(
21         `https://api.letsdeel.com/rest/v2${endpoint}`,
22         options
23       );
24 
25       return response.json();
26     });
27   }
28 
29   // Convenience methods
30   get(endpoint) { return this.makeRequest('GET', endpoint); }
31   post(endpoint, data) { return this.makeRequest('POST', endpoint, data); }
32   patch(endpoint, data) { return this.makeRequest('PATCH', endpoint, data); }
33 }
34 
35 // Single instance shared across your application
36 const deelClient = new CentralizedAPIClient();
37 
38 // All parts of your app use the same client
39 const contracts = await deelClient.get('/contracts');
40 const newContract = await deelClient.post('/contracts', contractData);

Important: Since rate limits are per organization, using multiple tokens won’t increase your rate limit. Instead, coordinate all API requests through a centralized queue.

Best Practices Summary

Do's

✅ Always implement request queuing

✅ Use exponential backoff for 429 retries

✅ Cache frequently accessed data

✅ Space out requests (avoid bursts)

✅ Set up alerts for rate limit errors

✅ Monitor 429 error frequency

✅ Centralize API requests across your organization

Don'ts

❌ Don’t send bursts of requests

❌ Don’t ignore 429 errors

❌ Don’t retry immediately without delay

❌ Don’t make unnecessary API calls

❌ Don’t use tight polling loops

❌ Don’t assume you know remaining quota (no headers provided)

❌ Don’t run multiple uncoordinated processes making API calls

Troubleshooting

Frequently hitting rate limits

Solutions:

Implement request queuing (most important!)
Add caching layer
Batch operations where possible
Review if all requests are necessary
Space out requests more (reduce from 5/sec to 4/sec for safety margin)
Identify and optimize high-volume operations

Unpredictable rate limiting

Possible causes:

Multiple services/processes making requests simultaneously
Background jobs running concurrently
Different parts of your application not coordinating requests
Rate limit shared across entire organization

Solutions:

Centralize all API requests through a single queue
Coordinate between services (use Redis or similar for distributed rate limiting)
Monitor which services are making requests
Implement request prioritization

Rate limits affecting production

Immediate actions:

Enable request queuing immediately
Increase delays between requests (use 4/sec instead of 5/sec)
Implement caching for frequently accessed data
Identify services making excessive requests
Contact Deel support if you need higher limits

Next Steps

Idempotency

Learn about safe request retries

Best Practices

Comprehensive integration best practices

Error Handling

Implement robust error handling

Webhooks

Reduce polling with webhooks

Overview

Deel enforces rate limits to ensure API stability and fair usage across all integrations. Understanding and respecting these limits is essential for building reliable applications.

Each organization can make up to 5 API requests per second across all tokens.
The rate limit is shared organization-wide, regardless of how many API tokens you use.
If you exceed your rate limit, the API will return a 429 Too Many Requests error.
Rate limiting uses a rolling 1-second window that automatically resets each second.

Rate Limit Details

Current Limits

Metric	Limit
Requests per second	5
Scope	Per organization
Window	1 second (rolling)
Error code	429 Too Many Requests

How It Works

The rate limit operates on a rolling 1-second window:

Second 1: ✅ ✅ ✅ ✅ ✅ (5 requests - OK)
Second 2: ❌ (6th request - rate limited!)
// Wait for next cycle
Second 3: ✅ ✅ ✅ ✅ ✅ (5 requests - OK again)

When you exceed 5 requests per second:

Additional requests receive a 429 status code
You must wait until the next cycle starts
The limit automatically resets each second

Handling Rate Limit Errors

Deel API does not return rate limit headers. You won’t know you’ve hit the rate limit until you receive a 429 error. This makes proactive rate limiting especially important.

When you exceed the rate limit, you’ll receive a 429 error:

1 {
2   "error": "Rate limit exceeded",
3   "status": 429,
4   "message": "Too many requests. Please wait before retrying."
5 }

Best Practice: Exponential Backoff

Implement exponential backoff when hitting rate limits:

1 async function makeRequestWithRetry(url, options, maxRetries = 3) {
2   for (let attempt = 0; attempt < maxRetries; attempt++) {
3     try {
4       const response = await fetch(url, options);
5 
6       // Success
7       if (response.ok) {
8         return await response.json();
9       }
10 
11       // Rate limited
12       if (response.status === 429) {
13         const retryAfter = response.headers.get('Retry-After') || 1;
14         const delay = Math.min(Math.pow(2, attempt) * 1000, 5000); // Max 5s
15 
16         console.log(`Rate limited. Waiting ${delay}ms before retry...`);
17         await new Promise(resolve => setTimeout(resolve, delay));
18         continue;
19       }
20 
21       // Other errors
22       throw new Error(`HTTP ${response.status}: ${response.statusText}`);
23 
24     } catch (error) {
25       if (attempt === maxRetries - 1) throw error;
26 
27       const delay = Math.pow(2, attempt) * 1000;
28       await new Promise(resolve => setTimeout(resolve, delay));
29     }
30   }
31 }

Strategies to Stay Within Limits

1. Request Queuing (Most Important)

Queue requests to ensure you never exceed 5 requests per second:

1 class RateLimitedQueue {
2   constructor(requestsPerSecond = 5) {
3     this.queue = [];
4     this.interval = 1000 / requestsPerSecond; // 200ms between requests
5     this.processing = false;
6     this.lastRequestTime = 0;
7   }
8 
9   async add(requestFn) {
10     return new Promise((resolve, reject) => {
11       this.queue.push({ requestFn, resolve, reject });
12       if (!this.processing) this.process();
13     });
14   }
15 
16   async process() {
17     this.processing = true;
18 
19     while (this.queue.length > 0) {
20       const { requestFn, resolve, reject } = this.queue.shift();
21 
22       // Ensure minimum interval between requests
23       const now = Date.now();
24       const timeSinceLastRequest = now - this.lastRequestTime;
25       if (timeSinceLastRequest < this.interval) {
26         await new Promise(r => setTimeout(r, this.interval - timeSinceLastRequest));
27       }
28 
29       try {
30         const result = await requestFn();
31         resolve(result);
32       } catch (error) {
33         reject(error);
34       }
35 
36       this.lastRequestTime = Date.now();
37     }
38 
39     this.processing = false;
40   }
41 }
42 
43 // Usage
44 const queue = new RateLimitedQueue(5); // 5 requests per second
45 
46 // Queue multiple requests
47 const results = await Promise.all([
48   queue.add(() => deelAPI.get('/contracts/1')),
49   queue.add(() => deelAPI.get('/contracts/2')),
50   queue.add(() => deelAPI.get('/contracts/3')),
51   // ... up to hundreds of requests
52 ]);

2. Batch Requests

When possible, use batch operations instead of individual requests:

1 // ❌ Inefficient - 100 individual requests
2 for (const contractId of contractIds) {
3   await getContract(contractId);
4 }
5 
6 // ✅ Efficient - Single batch request (if supported)
7 const contracts = await getContracts({ ids: contractIds });

3. Space Out Requests

Avoid bursts of requests. Spread them out over time:

1 // ❌ Bad - Burst of 20 requests at once
2 await Promise.all(
3   contractIds.map(id => getContract(id))
4 );
5 
6 // ✅ Good - Controlled rate
7 for (const id of contractIds) {
8   await getContract(id);
9   await sleep(200); // 200ms between requests = 5/second
10 }

4. Cache Responses

Reduce API calls by caching frequently accessed data:

1 const NodeCache = require('node-cache');
2 const cache = new NodeCache({ stdTTL: 300 }); // 5 minute TTL
3 
4 async function getCachedContract(contractId) {
5   // Check cache first
6   const cached = cache.get(`contract_${contractId}`);
7   if (cached) {
8     console.log('Cache hit');
9     return cached;
10   }
11 
12   // Fetch from API if not cached
13   const contract = await deelAPI.get(`/contracts/${contractId}`);
14 
15   // Store in cache
16   cache.set(`contract_${contractId}`, contract);
17 
18   return contract;
19 }

5. Centralize API Requests

Since rate limits are organization-wide, centralize request handling to avoid conflicts:

1 class CentralizedAPIClient {
2   constructor() {
3     this.queue = new RateLimitedQueue(5);
4   }
5 
6   async makeRequest(method, endpoint, data = null) {
7     return this.queue.add(async () => {
8       const options = {
9         method,
10         headers: {
11           'Authorization': `Bearer ${process.env.DEEL_API_TOKEN}`,
12           'Content-Type': 'application/json'
13         }
14       };
15 
16       if (data) {
17         options.body = JSON.stringify(data);
18       }
19 
20       const response = await fetch(
21         `https://api.letsdeel.com/rest/v2${endpoint}`,
22         options
23       );
24 
25       return response.json();
26     });
27   }
28 
29   // Convenience methods
30   get(endpoint) { return this.makeRequest('GET', endpoint); }
31   post(endpoint, data) { return this.makeRequest('POST', endpoint, data); }
32   patch(endpoint, data) { return this.makeRequest('PATCH', endpoint, data); }
33 }
34 
35 // Single instance shared across your application
36 const deelClient = new CentralizedAPIClient();
37 
38 // All parts of your app use the same client
39 const contracts = await deelClient.get('/contracts');
40 const newContract = await deelClient.post('/contracts', contractData);

Important: Since rate limits are per organization, using multiple tokens won’t increase your rate limit. Instead, coordinate all API requests through a centralized queue.

Best Practices Summary

Do's

✅ Always implement request queuing

✅ Use exponential backoff for 429 retries

✅ Cache frequently accessed data

✅ Space out requests (avoid bursts)

✅ Set up alerts for rate limit errors

✅ Monitor 429 error frequency

✅ Centralize API requests across your organization

Don'ts

❌ Don’t send bursts of requests

❌ Don’t ignore 429 errors

❌ Don’t retry immediately without delay

❌ Don’t make unnecessary API calls

❌ Don’t use tight polling loops

❌ Don’t assume you know remaining quota (no headers provided)

❌ Don’t run multiple uncoordinated processes making API calls

Troubleshooting

Frequently hitting rate limits

Solutions:

Implement request queuing (most important!)
Add caching layer
Batch operations where possible
Review if all requests are necessary
Space out requests more (reduce from 5/sec to 4/sec for safety margin)
Identify and optimize high-volume operations

Unpredictable rate limiting

Possible causes:

Multiple services/processes making requests simultaneously
Background jobs running concurrently
Different parts of your application not coordinating requests
Rate limit shared across entire organization

Solutions:

Centralize all API requests through a single queue
Coordinate between services (use Redis or similar for distributed rate limiting)
Monitor which services are making requests
Implement request prioritization

Rate limits affecting production

Immediate actions:

Enable request queuing immediately
Increase delays between requests (use 4/sec instead of 5/sec)
Implement caching for frequently accessed data
Identify services making excessive requests
Contact Deel support if you need higher limits

Next Steps

Idempotency

Learn about safe request retries

Best Practices

Comprehensive integration best practices

Error Handling

Implement robust error handling

Webhooks

Reduce polling with webhooks

1	{
2	"error": "Rate limit exceeded",
3	"status": 429,
4	"message": "Too many requests. Please wait before retrying."
5	}

1	async function makeRequestWithRetry(url, options, maxRetries = 3) {
2	for (let attempt = 0; attempt < maxRetries; attempt++) {
3	try {
4	const response = await fetch(url, options);
5
6	// Success
7	if (response.ok) {
8	return await response.json();
9	}
10
11	// Rate limited
12	if (response.status === 429) {
13	const retryAfter = response.headers.get('Retry-After') \|\| 1;
14	const delay = Math.min(Math.pow(2, attempt) * 1000, 5000); // Max 5s
15
16	console.log(`Rate limited. Waiting ${delay}ms before retry...`);
17	await new Promise(resolve => setTimeout(resolve, delay));
18	continue;
19	}
20
21	// Other errors
22	throw new Error(`HTTP ${response.status}: ${response.statusText}`);
23
24	} catch (error) {
25	if (attempt === maxRetries - 1) throw error;
26
27	const delay = Math.pow(2, attempt) * 1000;
28	await new Promise(resolve => setTimeout(resolve, delay));
29	}
30	}
31	}

1	class RateLimitedQueue {
2	constructor(requestsPerSecond = 5) {
3	this.queue = [];
4	this.interval = 1000 / requestsPerSecond; // 200ms between requests
5	this.processing = false;
6	this.lastRequestTime = 0;
7	}
8
9	async add(requestFn) {
10	return new Promise((resolve, reject) => {
11	this.queue.push({ requestFn, resolve, reject });
12	if (!this.processing) this.process();
13	});
14	}
15
16	async process() {
17	this.processing = true;
18
19	while (this.queue.length > 0) {
20	const { requestFn, resolve, reject } = this.queue.shift();
21
22	// Ensure minimum interval between requests
23	const now = Date.now();
24	const timeSinceLastRequest = now - this.lastRequestTime;
25	if (timeSinceLastRequest < this.interval) {
26	await new Promise(r => setTimeout(r, this.interval - timeSinceLastRequest));
27	}
28
29	try {
30	const result = await requestFn();
31	resolve(result);
32	} catch (error) {
33	reject(error);
34	}
35
36	this.lastRequestTime = Date.now();
37	}
38
39	this.processing = false;
40	}
41	}
42
43	// Usage
44	const queue = new RateLimitedQueue(5); // 5 requests per second
45
46	// Queue multiple requests
47	const results = await Promise.all([
48	queue.add(() => deelAPI.get('/contracts/1')),
49	queue.add(() => deelAPI.get('/contracts/2')),
50	queue.add(() => deelAPI.get('/contracts/3')),
51	// ... up to hundreds of requests
52	]);

1	// ❌ Inefficient - 100 individual requests
2	for (const contractId of contractIds) {
3	await getContract(contractId);
4	}
5
6	// ✅ Efficient - Single batch request (if supported)
7	const contracts = await getContracts({ ids: contractIds });

1	// ❌ Bad - Burst of 20 requests at once
2	await Promise.all(
3	contractIds.map(id => getContract(id))
4	);
5
6	// ✅ Good - Controlled rate
7	for (const id of contractIds) {
8	await getContract(id);
9	await sleep(200); // 200ms between requests = 5/second
10	}

1	const NodeCache = require('node-cache');
2	const cache = new NodeCache({ stdTTL: 300 }); // 5 minute TTL
3
4	async function getCachedContract(contractId) {
5	// Check cache first
6	const cached = cache.get(`contract_${contractId}`);
7	if (cached) {
8	console.log('Cache hit');
9	return cached;
10	}
11
12	// Fetch from API if not cached
13	const contract = await deelAPI.get(`/contracts/${contractId}`);
14
15	// Store in cache
16	cache.set(`contract_${contractId}`, contract);
17
18	return contract;
19	}

1	class CentralizedAPIClient {
2	constructor() {
3	this.queue = new RateLimitedQueue(5);
4	}
5
6	async makeRequest(method, endpoint, data = null) {
7	return this.queue.add(async () => {
8	const options = {
9	method,
10	headers: {
11	'Authorization': `Bearer ${process.env.DEEL_API_TOKEN}`,
12	'Content-Type': 'application/json'
13	}
14	};
15
16	if (data) {
17	options.body = JSON.stringify(data);
18	}
19
20	const response = await fetch(
21	`https://api.letsdeel.com/rest/v2${endpoint}`,
22	options
23	);
24
25	return response.json();
26	});
27	}
28
29	// Convenience methods
30	get(endpoint) { return this.makeRequest('GET', endpoint); }
31	post(endpoint, data) { return this.makeRequest('POST', endpoint, data); }
32	patch(endpoint, data) { return this.makeRequest('PATCH', endpoint, data); }
33	}
34
35	// Single instance shared across your application
36	const deelClient = new CentralizedAPIClient();
37
38	// All parts of your app use the same client
39	const contracts = await deelClient.get('/contracts');
40	const newContract = await deelClient.post('/contracts', contractData);