# Rate limits



API rate limits help protect Krenalis from excessive traffic and maintain consistent availability. Because limits are configured independently for each organization, their values may vary. Contact your platform administrator to learn which limits apply to your organization. If you are a platform administrator, you can use a [Platform Management API key](https://www.krenalis.com/docs/api/authentication.md#api-section-platform-management-key) to view and modify an [organization's rate limits](https://www.krenalis.com/docs/api/organizations.md).

The API applies separate limits to **organization-level requests**, **requests targeting a specific workspace**, and **events ingested into a workspace**. Applications should always be prepared to handle rate limiting, even when their expected traffic is well below the configured values.

## Handle rate-limit responses

When the API cannot accept a request because of rate limiting, it returns **`429 Too Many Requests`**. The response includes a **`Retry-After`** header whose value specifies the number of seconds your application must wait before retrying the request. Do not retry until this interval has elapsed.

For example:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 5
```

Avoid retrying many requests at the same time, because synchronized retries can immediately exhaust the available capacity again.

## Rate-limit categories

Each organization has three independent categories of rate limits.

### Organization requests

The organization limit applies to organization-level API requests. Requests targeting a specific workspace and event ingestion requests are excluded because they are controlled by separate limits.

All organization-level requests within the organization share the same available capacity.

### Workspace requests

The workspace limit applies to API requests targeting a specific workspace, excluding event ingestion requests. Each workspace has its own available capacity, so requests sent to one workspace do not consume the capacity available to another workspace.

### Event ingestion

The event ingestion limit applies to events ingested into a specific workspace. Unlike the other limits, it counts **individual events rather than API requests**. A request containing multiple events consumes one unit of capacity for each event included in the request.

The limit applies independently to each workspace.

## How rate limits work

Rate limits use a **token bucket** algorithm. Each limit is defined by a **rate per minute** and a **max capacity**.

The rate per minute determines how quickly capacity becomes available. For organization and workspace limits, each API request consumes one unit of capacity. For event ingestion limits, each event consumes one unit, including events submitted together in the same request.

The max capacity determines how much unused capacity can accumulate. When enough capacity is available, the API can accept a temporary burst above the configured per-minute rate. After that capacity has been consumed, additional requests or events can be accepted only as new capacity becomes available.

Treat the configured rate as a **limit rather than a target throughput**. Distribute traffic over time and leave enough margin for concurrent requests, retries, and temporary traffic spikes.

## Approximate enforcement

Rate-limit enforcement is distributed and should be considered **approximate**. Service instances may reserve portions of the available capacity for local use, which means that the observed request or event rate may temporarily differ from the configured values.

For this reason, applications should not use rate limits as an exact accounting, synchronization, or concurrency-control mechanism.