Rate Limits - Dutchie Point of Sale API

⚡ Rate Limits

The Dutchie Point of Sale API implements fair usage policies to ensure optimal performance for all users. Our rate limits are designed to accommodate normal business operations while preventing abuse.

📊 Rate Limit Structure

Rate limits are applied per-endpoint and per-API-key, measured in requests per minute. The API uses a baseline rate limit with endpoint-specific variations based on resource intensity and usage patterns.

🎯 Rate Limit Tiers

Endpoint Category	Rate Limit	Examples	Reasoning
Standard Endpoints	`120/min`	GET /products, GET /customers	Baseline rate for most operations
High-Traffic Endpoints	`200/min`	GET /inventory, GET /whoami	Frequently accessed, optimized data
Resource-Intensive	`60/min`	Reporting endpoints	Complex queries, larger datasets
Bulk Operations	`10/min`	Batch imports, bulk updates	High server resource usage

💡 Baseline Rate: The standard rate limit is 120 requests per minute per API key. Most endpoints use this baseline unless specifically configured otherwise for performance reasons.

🔍 Finding Endpoint Rate Limits

Each endpoint's specific rate limit is documented in its API reference documentation under the "Performance & Limits" section. Look for:

Endpoint Documentation - Check the specific endpoint's documentation for its rate limit
API Explorer - Rate limits are shown in the interactive API documentation
Default Assumption - If no specific rate limit is mentioned, assume the baseline 120/min

⚠️ Rate Limit Changes: Rate limits may be adjusted based on system performance and usage patterns. Always refer to the current endpoint documentation for the most up-to-date limits.

🚨 Rate Limit Exceeded

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "Message": "Too many requests - only 120 per minute allowed",
  "TraceId": "0HM2AFJV13H6F:00000001"
}

Handling Rate Limits

Implement exponential backoff - Gradually increase wait times for repeated failures
Monitor request patterns - Track your request frequency to avoid hitting limits
Cache responses - Reduce API calls by caching frequently accessed data
Use batch operations - Prefer bulk endpoints when available

🔧 Best Practices

Efficient API Usage

Batch Requests - Use bulk endpoints when available rather than individual calls
Filtering - Use query parameters to request only the data you need
Incremental Sync - Use modified date filters to sync only changed data
Pagination - Use paginated endpoints for large datasets

Error Handling

Retry Logic - Implement automatic retries with appropriate delays
Circuit Breakers - Stop making requests temporarily after repeated failures
Logging - Track rate limit usage patterns for optimization
Alerting - Monitor for approaching rate limits in production

🎯 Rate Limit Planning & Optimization

📊 Capacity Planning

Plan your integration based on the baseline 120 requests/minute (2 requests/second) rate limit:

Hourly Capacity - 7,200 requests per hour (120 × 60)
Daily Capacity - 172,800 requests per day (120 × 60 × 24)
Safety Margin - Plan for 80% of capacity (96 requests/minute) to handle spikes
Burst Prevention - Spread requests evenly rather than in bursts

🎯 Planning Example: If you need to sync 1,000 customers daily, that's ~42 API calls per hour, well within the 7,200/hour capacity. You can safely sync every 5 minutes during business hours.

Data Caching Strategy

Product Catalogs - Cache for 1-4 hours (change infrequently)
Customer Data - Cache for 15-60 minutes with reasonable TTL
Inventory Levels - Cache for 1-5 minutes (higher change frequency)
Reports - Cache for several hours or daily (resource-intensive endpoints)

Request Distribution

Even Distribution - Spread 120 requests evenly across each minute
Peak Hour Planning - Account for business hour traffic spikes
Batch Operations - Use sparingly due to lower limits (10/min)
Background Sync - Schedule heavy syncing during off-peak hours

Monitoring and Alerting

Usage Tracking - Monitor requests per minute against your limits
Alert Thresholds - Set alerts at 80% of rate limit capacity
Pattern Analysis - Track usage patterns to optimize timing
Error Monitoring - Watch for 429 responses indicating limit breaches