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

# Rate Limiting

The anny API enforces rate limits to protect platform stability and ensure fair usage. Limits vary by **authentication level** (admin, customer, anonymous) and **operation type** (read vs. write).

***

## How It Works

Every request is classified along two dimensions:

1. **Identity** — resolved from the access token:
   * **Admin** — authenticated team member (via Admin API)
   * **Customer** — authenticated end-user (via Customer API)
   * **Anonymous** — no token provided (public endpoints)

2. **Operation type**:
   * **Reads** — `GET` requests
   * **Writes** — `POST`, `PATCH`, `PUT`, `DELETE` requests

Each combination of identity and operation type has its own request budget per time window.

***

## Default Limits

<Info>
  Limits are configured per organization and may be adjusted upon request. The values below are the platform defaults.
</Info>

| Identity      | Reads               | Writes              |
| ------------- | ------------------- | ------------------- |
| **Admin**     | 400 requests / 60 s | 100 requests / 60 s |
| **Customer**  | 150 requests / 60 s | 60 requests / 60 s  |
| **Anonymous** | 150 requests / 60 s | 60 requests / 60 s  |

### Identical Request Guard

In addition to the per-identity limits above, the API enforces a **duplicate request guard**: at most **4 identical requests per second**. Two requests are considered identical when they share the same HTTP method, path, query parameters, and JSON body.

This prevents accidental request floods from retry loops or UI bugs without impacting normal usage.

***

## Response Headers

When a rate limit is exceeded, the API responds with HTTP status **`429 Too Many Requests`**:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json
```

```json theme={null}
{
  "errors": [
    {
      "status": "429",
      "title": "Too Many Requests",
      "detail": "Too many requests."
    }
  ]
}
```

| Header        | Description                                                     |
| ------------- | --------------------------------------------------------------- |
| `Retry-After` | Seconds until the limit resets and requests are accepted again. |

<Warning>
  The API does **not** include `X-RateLimit-Remaining` or `X-RateLimit-Limit` headers on successful responses. You should implement your own request counting on the client side if you need to track remaining quota.
</Warning>

***

## Best Practices

<Steps>
  <Step title="Use Exponential Backoff">
    When you receive a `429` response, wait at least the number of seconds indicated by the `Retry-After` header before retrying. Increase the delay on subsequent retries.
  </Step>

  <Step title="Avoid Duplicate Requests">
    Debounce user-triggered actions (e.g. save buttons) and deduplicate programmatic calls. The identical-request guard will block rapid-fire duplicates.
  </Step>

  <Step title="Use Sparse Fieldsets & Filters">
    Reduce the number of requests by fetching only the data you need. Use `fields[]` and `filter[]` parameters to minimize round-trips — see [JSON:API Conventions](/developers/guides/json-api-conventions).
  </Step>

  <Step title="Cache Where Possible">
    Cache responses for data that changes infrequently (e.g. resource lists, service configurations). This keeps you well within rate limits during normal operation.
  </Step>
</Steps>

***

## Admin API vs. Customer API

The Admin API grants higher limits because admin integrations typically manage bulk operations (exports, calendar sync, multi-booking workflows). The Customer API is tuned for interactive end-user flows like searching availability and completing checkouts.

| Scenario                       | API          | Typical Budget   |
| ------------------------------ | ------------ | ---------------- |
| Dashboard sync, bulk exports   | Admin API    | 400 reads / min  |
| POS / booking terminal         | Admin API    | 100 writes / min |
| Storefront availability search | Customer API | 150 reads / min  |
| Checkout & booking creation    | Customer API | 60 writes / min  |
| Public embed (no auth)         | Customer API | 150 reads / min  |

If your integration requires higher throughput, contact [support@anny.co](mailto:support@anny.co) to discuss custom limits.