Rate Limiting

Overview

To ensure fair usage and maintain optimal performance for all users, the Curosa API implements rate limiting on all endpoints. Rate limits help protect the API from being overwhelmed and ensure reliable service for everyone.

Rate Limits

Rate limits are applied per endpoint:

• Login endpoint (POST /login): 10 requests per hour
• All other documented API endpoints: 3,600 requests per hour

Always refer to endpoint-specific docs for any exceptions.

Rate Limit Headers

Each API response includes rate limit headers so you can monitor usage in real time:

• x-ratelimit-limit: The request limit for the current window
• x-ratelimit-remaining: Requests remaining in the current window

Rate Limit Responses

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

{"success":false,"message":"Too many requests. Please try again later."}

If you receive this response, you should pause your requests and retry after a short delay.

Best Practices

To avoid hitting rate limits and ensure optimal API usage, follow these recommendations:

1. Implement Exponential Backoff

When you receive a 429 response, implement exponential backoff in your retry logic:

• Wait 1 second before the first retry
• Double the wait time for each subsequent retry (2s, 4s, 8s, etc.)
• Set a maximum retry limit to prevent infinite loops

Example retry logic:

Initial request fails → Wait 1s → Retry
Still failing → Wait 2s → Retry
Still failing → Wait 4s → Retry

2. Cache Responses Where Appropriate

Reduce unnecessary API calls by caching responses that don't change frequently:

• Cache reference data (product catalogs, categories, etc.)
• Set appropriate cache expiration times based on data volatility
• Use conditional requests when available

3. Use Webhooks Instead of Polling

Rather than repeatedly polling endpoints for updates, use webhooks to receive real-time notifications:

• Webhooks push updates to you automatically
• Eliminates the need for frequent polling requests
• More efficient and reduces load on both systems
• See the Webhooks documentation for setup instructions

4. Batch Requests When Possible

If you need to retrieve multiple resources, check if the API supports batch operations to reduce the number of individual requests.

5. Monitor Your Usage

Keep track of your API usage patterns and adjust your integration to stay well within rate limits, leaving room for spikes in activity.

Need Higher Limits?

If your application requires higher rate limits, please contact our support team to discuss your use case and explore available options.