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

# Маҳдудияти дархостҳо

> Равзанаи техникӣ барои ҳар калид, ки дар сарлавҳаҳои ҷавобҳои муваффақи JSON ва дар 429 нишон дода мешавад.

Ҳар калид равзанаи худро дорад: **120 дархост дар 60 сония** ба таври пешфарз. Ин сақфи амалиётӣ бар зидди суиистифода аст, на квотаи тариф. Худи истифода аз рӯи баланси соҳиб ҳисоб мешавад, на аз рӯи ин ҳисобкунак, ва калидҳои ҳамон соҳиб равзанаро муштарак истифода намебаранд.

Аутентификатсия пеш аз маҳдудкунанда иҷро мешавад, бинобар ин дархости беаутентификатсия ҳеҷ гоҳ буҷети калидро сарф намекунад.

## Сарлавҳаҳо

Ҷавобҳои муваффақи JSON (`200`) ва ҷавоби `429` ҳолати равзанаро мебаранд:

| Сарлавҳа                | Маъно                                              |
| ----------------------- | -------------------------------------------------- |
| `X-RateLimit-Limit`     | Дархостҳои иҷозатдодашуда дар як равзана           |
| `X-RateLimit-Remaining` | Дархостҳои боқимонда дар равзанаи ҷорӣ             |
| `X-RateLimit-Reset`     | Вақти Unix (сония), ки равзана аз нав оғоз мешавад |

Ҷавоби `text/event-stream`-и эндпоинти ҷараёнӣ ва конвертҳои дигари хато (`401`, `403`, `404`, `409`, `422`, `503`, `500`) ин сарлавҳаҳоро намебаранд; танҳо `X-Request-ID` дар ҳар ҷавоб ҳаст. Агар шумо мизоҷро аз рӯи `X-RateLimit-Remaining` танзим кунед, сарлавҳаи ғоибро ҳамчун «номаълум» қабул кунед, на ҳамчун сифр.

Вақте ки равзана тамом мешавад, API `429 rate_limit_exceeded` ҷавоб медиҳад ва `Retry-After`-ро (сонияҳо то аз нав оғоз шудани равзана) илова мекунад.

```http theme={null}
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1789470060
Retry-After: 17
X-Request-ID: 7f20a5f0-5dde-48cf-94aa-38acbbd218e0

{"error": {"code": "rate_limit_exceeded", "message": "Rate limit exceeded for this API key; try again later", "request_id": "7f20a5f0-5dde-48cf-94aa-38acbbd218e0"}}
```

## Вақте ки худи маҳдудкунанда кор намекунад

Маҳдудкунанда ба таври **пӯшида** ноком мешавад. Агар анбори он дастнорас бошад, API ба ҷои гузаронидани дархостҳо бидуни ҳисоб ва ба ҷои 429-и гумроҳкунанда `503 api_rate_limit_unavailable` бо `Retry-After: 5` ҷавоб медиҳад. Онро мисли ҳар хатои муваққатии дигар қабул кунед: интизор шавед ва бо ҳамон `Idempotency-Key` такрор кунед.

<Warning>
  Барои баланд кардани сақф трафикро байни якчанд калиди ҳамон агент тақсим накунед. Ҳар калид муколамаҳои худро дорад, бинобар ин ҳамон корбари ниҳоӣ таърихи пароканда мегирад. Агар ба шумо лимити баландтар лозим бошад, бо мо тамос гиред.
</Warning>

## Танзими суръат дар тарафи мизоҷ

<CodeGroup>
  ```bash curl theme={null}
  # Retries on 429/503 after Retry-After, then prints the window state of the final answer.
  while :; do
    status=$(curl -s -o /dev/null -D headers.txt -w '%{http_code}' \
      "$CHATTLER_BASE_URL/v1/agents/$CHATTLER_AGENT_ID/conversations?limit=20" \
      -H "Authorization: Bearer $CHATTLER_API_KEY")
    if [ "$status" = "429" ] || [ "$status" = "503" ]; then
      sleep "$(grep -i '^Retry-After:' headers.txt | tr -d '\r' | awk '{print $2}')"
      continue
    fi
    grep -i '^X-RateLimit-' headers.txt
    break
  done
  ```

  ```python Python theme={null}
  import time

  import httpx


  def request_with_pacing(method: str, url: str, **kwargs) -> httpx.Response:
      while True:
          response = httpx.request(method, url, headers=HEADERS, timeout=120, **kwargs)
          if response.status_code in (429, 503):
              time.sleep(float(response.headers.get("Retry-After", "5")))
              continue
          if int(response.headers.get("X-RateLimit-Remaining", "1")) == 0:
              reset_at = int(response.headers.get("X-RateLimit-Reset", "0"))
              time.sleep(max(0.0, reset_at - time.time()))
          return response
  ```

  ```javascript Node theme={null}
  async function requestWithPacing(url, init = {}) {
    for (;;) {
      const response = await fetch(url, {
        ...init,
        headers: { Authorization: `Bearer ${apiKey}`, ...(init.headers ?? {}) },
      });
      if (response.status === 429 || response.status === 503) {
        const wait = Number(response.headers.get("Retry-After") ?? 5);
        await new Promise((r) => setTimeout(r, wait * 1000));
        continue;
      }
      if (response.headers.get("X-RateLimit-Remaining") === "0") {
        const resetAt = Number(response.headers.get("X-RateLimit-Reset") ?? 0) * 1000;
        await new Promise((r) => setTimeout(r, Math.max(0, resetAt - Date.now())));
      }
      return response;
    }
  }
  ```
</CodeGroup>