> ## Documentation Index
> Fetch the complete documentation index at: https://docs.everabyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> How the per-key limiter works, how to handle 429 responses, and what happens during a Redis outage.

## The limit

Each API key has a request rate limit:

| Property | Value |
| - | - |
| Default | 600 requests per minute |
| Window | 60 seconds |
| Scope | Per API key |
| Configuration | Deployment setting `API_KEY_RATE_LIMIT_PER_MIN` |
| Response when exceeded | `429` with `code: "API_KEY_RATE_LIMITED"` |

The limiter counts requests, not bytes and not endpoint cost. A small metadata read and a large download both consume one request.

## What happens when you exceed it

```json theme={null}
{
  "status": 429,
  "message": "API key rate limit exceeded. Retry shortly.",
  "data": null,
  "code": "API_KEY_RATE_LIMITED"
}
```

The rejection happens after authentication and bucket-scope checks, but before the route handler runs. No file operation is performed.

No `Retry-After` header is documented. Do not depend on one.

## Recommended client behavior

**1. Stop immediately on 429**

Do not continue a tight retry loop. Each rejected request still represents load.

**2. Back off with jitter**

Start around one second, double up to a ceiling (for example 30 seconds), and add random jitter so concurrent workers do not retry in lockstep.

**3. Reduce concurrency**

If 429s persist, lower the number of parallel workers using the same key. The limit is per key, not per process.

**4. Split by workload**

Give independent services their own keys so one burst does not starve another integration.

## Fail-open behavior

If the limiter's Redis backing store is unavailable, the limiter fails open: requests are allowed rather than rejected. This avoids turning a cache outage into an API outage, but it means the limit is not enforced during that window.

Do not design your integration to rely on the limiter for safety. It is a fairness control, not an authorization or billing control.

## Limits are not the same as quotas

| Control | Purpose | Response |
| - | - | - |
| Rate limit | Requests per minute per key | `429 API_KEY_RATE_LIMITED` |
| Trial quota | Total calls during the trial window | `403 TRIAL_API_LIMIT_REACHED` |
| Subscription gate | Paid access required | `402 SUBSCRIPTION_REQUIRED` |
| Storage capacity | Bytes available on the plan | Upload error |

A `429` is temporary. A trial quota or subscription failure requires an account change.

## Bulk operations

For large migrations:

* Use one key per migration job.
* Process files sequentially or with low concurrency.
* Prefer listing endpoints with larger page sizes to reduce request count, within documented maximums.
* Pause between batches rather than relying on retries after 429.
* Record progress so a failed batch can resume without duplicating uploads.

## Monitoring

Track at least:

* request rate per key,
* 429 count and ratio,
* p95 and p99 latency,
* upload failure rate by status,
* trial remaining, if applicable.

Alert on sustained 429 ratios rather than individual spikes. A brief spike during a deployment is normal; a sustained 5% rejection rate is not.

## When to request a higher limit

If your workload is legitimate and consistently near the limit, contact [`support@everabyte.com`](mailto:support@everabyte.com) with:

* company ID,
* key public prefix,
* expected requests per minute,
* endpoint mix,
* business justification.

Do not create many keys to circumvent the limit. That fragments auditability and does not change the underlying capacity.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.