Rate Limiting

OpenMeter enforces rate limiting for the REST API to ensure fair usage and system stability.

#Rate Limit Configuration

OpenMeter enforces rate limiting on specific API endpoints with the following configuration:

#Rate Limit Headers

OpenMeter includes rate limit information in HTTP response headers for all requests to rate-limited endpoints:

• X-RateLimit-Limit: The maximum number of requests allowed per second
• X-RateLimit-Remaining: The number of requests remaining in the current time window
• X-RateLimit-Reset: The time (in Unix timestamp) when the rate limit resets
• Retry-After: When rate limited, this header indicates the number of seconds to wait before retrying the request

#Handling Rate Limits

When you exceed the rate limit, OpenMeter returns an HTTP 429 Too Many Requests status code. The Retry-After header will indicate how long you should wait before making another request.

To avoid hitting rate limits:

• Monitor the X-RateLimit-Remaining header to track your remaining requests
• Implement exponential backoff when you receive a 429 response
• Consider implementing async queues for high-volume scenarios
• Consider caching results for frequent requests

#Handle ingest bursts

In high-volume scenarios, we recommend to use the OpenMeter Collector to ingest events with buffering enabled. This allows you to ingest events even if the network is down for an extended period of time. When the network is restored, the collector will replay the buffered events to OpenMeter Cloud.

Read more about event buffering.

#Caching entitlement statuses

Avoid calling the Entitlement Value API on your critical request path.
Instead, use the Notifications to cache the entitlement status in your database.

Metered and boolean entitlements can be cached as simple true and false boolean flags in your database. To do this you can use the Notifications integration to receive events when an entitlement crosses the thresholds you configure (for example, when usage approaches or exceeds the allowed limit). Your application can then perform fast, local entitlement checks without repeatedly querying the OpenMeter API.

Caching entitlement status and receiving notifications provides several benefits:

• Removes entitlement lookups from performance-sensitive paths
• Reduces latency and external dependencies in your application
• Ensures your application reacts proactively to entitlement changes
• Allows you to centralize entitlement state alongside your business logic