Skip to main content

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.

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

​
Headers

HeaderMeaning
X-RateLimit-LimitMaximum requests allowed per window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the window resets
The RateLimitInfo message in 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: 
{
  "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.
  • 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.
  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.