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

# Rate Limits

> Per-key and per-user limits, response headers, and back-off strategy.

Every response carries rate-limit headers so clients can self-pace without guessing.

## Headers

| Header                  | Meaning                                         |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per window             |
| `X-RateLimit-Remaining` | Requests remaining in the current window        |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the window resets |

The `RateLimitInfo` message in [`sdk/shared/v1/rate_limit.proto`](https://github.com/anghami/sdk/blob/main/sdk/shared/v1/rate_limit.proto) documents the contract — the values arrive as headers, not in the response body.

## What to do when you're throttled

When you exceed the limit, the API returns HTTP `429` with a structured body:

```json theme={null}
{
  "code": "ERROR_CODE_RATE_LIMITED",
  "message": "Rate limit exceeded. Retry after 23s."
}
```

Honor `X-RateLimit-Reset` and back off until the window resets. Don't retry tighter than the reset window — repeated 429s extend the cool-down.

## Tiers

* **API key** — limits are billed per key and configured in the [Developer Portal](/developer-portal).
* **OAuth user tokens** — limits are per access token; sliding-window enforcement.
* **Stream acquisition** — `AcquireMusicStream` / `AcquireVideoStream` have their own concurrency cap separate from request-rate limits.

## Recommended client policy

1. Read `X-RateLimit-Remaining` on every response.
2. When it crosses below \~10% of `X-RateLimit-Limit`, slow your fan-out.
3. On `429`, sleep until `X-RateLimit-Reset`, jitter ±10%, then resume.
4. Surface throttling to your application metrics — sustained throttling means you should batch (`BatchGetSongs`, etc.) instead of fan-out.

## Batch endpoints reduce pressure

Use the `BatchGet*` operations on `MusicCatalogService` and `VideoCatalogService` whenever you need more than \~3 items of the same kind. One batch request counts as one call against the rate limit, regardless of how many items it returns. See [Music Catalog](/music-catalog).