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

# Rate limits

> Understand how rate limiting system works and what limits apply to your API usage.

To maintain platform stability and fair usage, we enforce rate limits on all API requests using a **token bucket algorithm**.

## How it works

The system uses **buckets of tokens** to manage how many requests each client can make:

* Each bucket has a **maximum capacity** (how many requests can be stored).
* Each request consumes tokens from a shared rate-limit bucket tied to your **organization**. This means all API keys under the same org count toward the same limits.
* Tokens are **refilled automatically over time**, at a set rate per second.
* When you make a request, **1 token is consumed**.
* If your bucket runs out of tokens, **your request is blocked** until more tokens are refilled.

This allows you to have burst periods when needed and doesn't block you from sending requests for a pre-determined amount of period.

## Identifier Scope

Rate limits **are applied per organization, not per IP address**.

Whenever possible, the rate limiter uses the most specific and reliable identifier available to track usage:

* **Organization ID** – Primary rate limit scope (tied to your API key)
* **API Key** – Used if org-level context is not clearly available
* **User ID** – Used if org-level context is not available
* **IP Address** – Only used as a last resort (e.g., unauthenticated or anonymous requests)

As a result, all requests made using the same organization's API keys will share the same rate-limiting bucket.

## Token buckets by tier

Rate limits vary based on your **organization's tier**. Each tier defines different capacities and refill rates depending on the type of request.

### Available request types

* `DEFAULT`: General-purpose requests (e.g., products, invoices, webhooks)
* `PAYMENTS`: High-sensitivity endpoints such as payment creation
* `AUTH`: Authentication-related requests (e.g., token exchanges, sessions)

### Tier limits

| Tier     | Type     | Capacity | Refill Rate (tokens/sec) |
| -------- | -------- | -------- | ------------------------ |
| `BASE`   | DEFAULT  | 50       | 5                        |
| `BASE`   | PAYMENTS | 10       | 1                        |
| `BASE`   | AUTH     | 5        | 1                        |
| `TIER_1` | DEFAULT  | 150      | 15                       |
| `TIER_1` | PAYMENTS | 50       | 5                        |
| `TIER_1` | AUTH     | 5        | 1                        |
| `TIER_2` | DEFAULT  | 450      | 45                       |
| `TIER_2` | PAYMENTS | 250      | 50                       |
| `TIER_2` | AUTH     | 5        | 1                        |
| `TIER_3` | DEFAULT  | 1000     | 100                      |
| `TIER_3` | PAYMENTS | 500      | 100                      |
| `TIER_3` | AUTH     | 5        | 1                        |

<Info>If you're unsure about your current tier or want to upgrade, please contact [hello@bitgpt.xyz](mailto:hello@bitgpt.xyz).</Info>

## Retry Behavior

When your bucket runs out of tokens:

* Your request will return an error with a `429 Too Many Requests` status.
* The response will include a `Retry-After` header (in seconds), which tells you how long to wait before retrying.

<Tip>Implementing retry logic with exponential backoff is strongly recommended to handle rate-limited responses gracefully.</Tip>

## Tips for Developers

* **Group related operations** to reduce the number of requests.
* **Cache frequently accessed data** instead of refetching it constantly.
* **Monitor response headers** for usage patterns and implement alerts when nearing limits.
* **Use `retry_after`** from the error response to delay your retry appropriately.

## Example Error Response (Rate Limit)

```json theme={"system"}
{
  "status": 429,
  "error": "Rate limit exceeded, try again in 5 seconds",
  "log": {
    "support": "Reach out to support@bitgpt.xyz to request a higher tier, or upgrade your plan. Read more at docs.bitgpt.xyz.",
    "rate_limit": {
      "resource": "example_resource",
      "tier": "BASE",
      "type": "DEFAULT"
    }
  }
}
```