Finch API Rate Limits: Technical Guide

Overview

Finch enforces application-level rate limits on a rolling 60-second window. Since data syncs from providers occur every 24 hours, rate limits are designed to accommodate daily data retrieval patterns while protecting system stability.

Rate Limits

Application-Level (per minute)

Rate limits apply across all access tokens for your application. Limits reset on a rolling 60-second basis per endpoint.

IP-Level

• Limit: 1,000 requests per 5 minutes

• Penalty: 60-minute lockout if exceeded

How Finch Data Syncing Works

Critical context: Finch syncs data from providers once every 24 hours per connection. The 24-hour timer starts after a sync completes (not when it begins). Sync duration varies from seconds to hours depending on company size, provider, and data type.

Implication: Calling the API more than once per day for the same connection returns identical data. There is no benefit to more frequent polling.

Webhook notification: job.data_sync_all.completed notifies you when fresh data is available.

Rate Limit Math by Scale

Understanding how your connection count and processing window affect rate limit utilization:

For 20 req/min endpoints (company, directory, individual, employment, documents)

For 12 req/min endpoints (payment, pay-statement, pay-groups)

*Exceeds rate limit - requires queuing or wider time window.

Time windows explained:

• 24 hours: Webhook-driven architecture (recommended) - syncs distributed throughout the day

• 8 hours: Scheduled batch processing during business hours - common for cron-based systems

Key insight: Webhook-driven architecture naturally distributes calls across 24 hours. Even at 10,000 connections, you average 7 calls/minute—well under the 20/minute limit.

Implementation Patterns

Webhook-Driven (Recommended)

Subscribe to job.data_sync_all.completed webhooks. When a webhook arrives, queue that connection for processing. Process the queue in parallel while respecting rate limits.

Scales to: 10,000+ connections with no rate limit issues

Staggered Cron Jobs

Divide connections into time-based batches. Process batches throughout the day or within specific windows. Use queue-based processing with rate limit awareness.

Example: 5,000 connections ÷ 240 minutes (4 hours) = 21 calls/minute (requires basic queuing)

Paginating Pay Statements for Large Companies

Most companies have <500 employees. For larger enterprise customers:

Example: 10,000 employees

• Batch size: 100 employees/request

• Total requests: 100 (sequential pagination for one payment)

• Time at 12 req/min: ~8 minutes

• Reality: Response processing (parsing, storing) adds 1-3 seconds per request, extending total time to 10-15 minutes

Example: 3,000 employees

• Total requests: 30

• Time: 2.5 minutes (3-5 minutes with processing)

How Pay Statement Pagination Works

The /pay-statement endpoint accepts multiple payment_ids in one request, but pagination applies separately to each payment.

Implication: Pagination for one payment must be sequential - you need to know when you've retrieved all records. However, you can process multiple connections' payments in parallel until you approach rate limits.

When Rate Limits Matter: Multiple Large Companies

Rate limits become a consideration when many large companies share pay dates:

Most common scenario: If you have 100 total connections, possibly 5-10 are large companies (1,000+ employees), and only 2-4 share the same pay date. This results in 200-400 requests = 17-33 minutes of processing twice per month.

Implementation Strategy

For <10 large companies on same day: Use a simple queue-based approach that processes one company's payment at a time.

For 10-20 large companies on same day: Stagger processing to smooth out rate limit usage. For example, add a 5-minute delay between starting each company's pagination.

For 20+ large companies on same day: If you have the Large Employer addon in your contract and regularly process 20+ companies with 3,000+ employees on the same pay dates, contact your Developer Success Engineer to discuss rate limit adjustments for your use case.

Why This Works

1. Infrequent operation: Pay statements are retrieved when new payments are available—weekly (52x/year), bi-weekly (26x/year), semi-monthly (24x/year), or monthly (12x/year)

2. Natural spacing: Processing 100 employees of data (parsing JSON, database writes) takes time, naturally spacing requests below the rate limit

3. Distributed pay dates: Even companies on "common" pay dates (1st, 15th, Fridays) are spread across different payroll providers and processing times

4. Webhook-driven: job.data_sync_all.completed webhooks naturally distribute processing as payments become available

When Rate Limits Actually Become a Constraint

Rate limits only cause issues when you:

• Batch all connections to sync simultaneously

• Use sequential processing instead of parallel

• Poll continuously instead of using webhooks

You're hitting rate limits if you see:

• 429 responses with finch_code: "finch_application_rl" or finch_code: "finch_api_ip_rl"

• Sync times that match rate limit math exactly (4,000 calls at 20/min = 200 minutes)

You're NOT hitting rate limits if:

• No 429 errors in logs

• Each request takes 3+ seconds total

• Sync time exceeds rate limit math (e.g., 4+ hours for 4,000 connections)

Troubleshooting Slow Syncs

"My system takes 4 hours to sync 4,000 connections"

Math check: 4,000 calls at 20/min = 200 minutes = 3.3 hours maximum

If it's taking 4 hours, the bottleneck is your architecture, not rate limits:

Common causes:

1. Sequential processing: Making one call, processing, then next call (not parallelized)

2. Synchronous database writes: Blocking on DB operations before next request

3. No connection pooling: Creating new HTTP connection per request

4. Inefficient data transformation: Heavy processing in request path

How to identify: Time each request from start to finish, breaking down: network time + processing time + database time. If total time per request exceeds 2 seconds, you need parallel processing.

Expected performance with proper architecture:

• 1,000 connections: 5-15 minutes

• 4,000 connections: 20-40 minutes

• 10,000 connections: 45-90 minutes

Fix: Implement parallel processing (10-20 concurrent requests), async database operations, and webhook-driven architecture.

Testing Rate Limits in Sandbox

Sandbox limit: 100 connections per application

You don't need thousands of connections to test rate limiting:

Option 1: Large Employee Datasets

• Standard: 20 employees per connection

• Extended: Up to 10,000 employees (requires approval from developers@tryfinch.com)

• 10 connections × 5,000 employees × 50 paginated requests = 500 API calls

See Testing Large Datasets Guide

Option 2: Small Page Sizes

Use smaller page sizes to force pagination with standard sandbox datasets. For example, 100 employees with limit=5 creates 20 pages per connection. With 100 connections, that's 2,000 paginated requests to test your rate limiting logic.

Option 3: Concurrent Processing

Process all 100 sandbox connections in parallel to test queue management and rate limiting.

Option 4: Intentional Rate Limit Triggering

Make rapid concurrent requests to the same endpoint to trigger 429 responses. Validate your retry logic and exponential backoff handling.

FAQ

Can we request higher rate limits?

Yes, if you have several thousand connections and have already:

• Implemented webhook-driven or queue-based architecture

• Enabled parallel processing

• Optimized your data pipeline

Contact your Developer Success Engineer with:

• Current connection count and architecture

• Rate limit errors you're experiencing

• How you've optimized your system

Note: Most slow syncs are caused by architecture issues, not rate limits. Higher limits won't fix sequential processing or synchronous database operations.

How do I know if rate limits are the problem?

You're hitting rate limits:

• 429 HTTP responses in logs

• finch_code: "finch_application_rl" errors

• Sync time matches rate limit math exactly

It's your architecture:

• No 429 errors

• Each request takes 3+ seconds

• Sync time exceeds rate limit calculations

We only sync weekly/monthly. Do rate limits matter?

No. Math:

• Weekly: 10,000 connections = 1 call/min average (5% of limit)

• Monthly: 10,000 connections = 0.23 calls/min average (1% of limit)

What if many employers connect simultaneously through Finch Connect?

Extremely unlikely. Employer authentication happens organically across business hours and days. Even during peak onboarding, rarely exceeds 10-20 connections per minute.

If 100 employers somehow connected in 5 minutes:

• Initial syncs run automatically

• You pull data after receiving job.data_sync_all.completed webhook

• By then, connections are distributed over time

Use webhook-driven architecture and this is never an issue.

How do I test rate limits with only 100 sandbox connections?

Use large employee datasets (up to 10,000 per connection), small page sizes (limit=5), and concurrent processing. You can generate 2,000+ API calls with proper configuration. See "Testing Rate Limits in Sandbox" above.

Should I implement rate limiting in my code?

Yes. Implement:

• Request queuing with controlled processing rate

• Retry logic with exponential backoff for 429 responses

• Monitoring of API calls per minute

• Circuit breakers for consistent limit hits

This makes your integration resilient to growth and edge cases.

Summary

Finch's rate limits accommodate standard integration patterns because data only refreshes once per 24 hours. Properly designed systems operate well below limits:

• Webhook-driven: Natural distribution across 24 hours

• 10,000 connections: Average 7 calls/minute (35% utilization)

• Pagination: Processing time naturally spaces requests

Rate limits become constraints only when batching all requests simultaneously instead of distributing appropriately.

For questions or custom rate limit discussions, contact support or your Developer Success Engineer.