# レート制限

> 組織単位の RPM/TPM 上限、429 の挙動、リトライガイド。

Source: https://kiln.bricksum.com/docs/ja/rate-limits

レート制限は組織単位で適用されます。現在のデフォルト値は次のとおりです。

- **リクエスト**: デフォルトで組織あたり 60 RPM（毎分リクエスト数）です。超過すると 429 が返されます。
- **トークン**: TPM（毎分トークン数）はデフォルトで無制限ですが、運用チームが組織ごとに上限を設定できます。超過すると 429 が返されます。
- **同時実行**: 組織あたり同時 8 リクエストです。8 件が処理中のときに届いたリクエストは、モデルに到達する前に即座に 429 で拒否されます。

メモ

組織の現在の上限はコンソールの組織 → 概要で確認できます。上記のデフォルト値はサービスの改善に伴って変わる可能性があります。負荷テストなどでより高い上限が必要な場合は、実行前にお問い合わせください。

## 上限を超えた場合

上限を超えると `429 Too Many Requests` が返されます。毎分リクエストまたは毎分トークンの 429 には `x-ratelimit-reset` （現在の 1 分ウィンドウがリセットされるまでの秒数）が含まれます。その他のヘッダーは上限の種類によって異なります。毎分リクエストの 429 には x-ratelimit-limit と x-ratelimit-remaining が、毎分トークンの 429 には x-ratelimit-limit-tokens と x-ratelimit-remaining-tokens が含まれます。同時実行の 429 は後段で返され、これらのヘッダーを一切含まないため、指数バックオフでリトライしてください。

## リトライガイド

- 429 と 5xx のレスポンスはリトライしてください。400/401/403 などの 4xx はリトライしないでください。
- ジッター付きの指数バックオフを使用してください（例：1 秒、2 秒、4 秒…と延ばし、上限を設ける）。
- 毎分リクエストまたは毎分トークンの 429 では遅延を推測せず、x-ratelimit-reset の秒数だけ待ってください。同時実行の 429 にはこのヘッダーがないため、指数バックオフを使用してください。
- リトライの総回数を制限し（例：5 回）、超えた場合はユーザーにわかりやすいエラーを表示してください。

ステータスコードで分岐し、レスポンスに x-ratelimit-reset があればその値を読むリトライループです。同時実行の 429 と 5xx にはリセットヘッダーがないため、指数バックオフを使用します。

**Python**
```python
import random
import time

def post_with_retry(client, path, payload, max_attempts=5):
    for attempt in range(max_attempts):
        r = client.post(path, json=payload)
        if r.status_code < 400:
            return r
        # 400, 401, 402, 403, 404 and 405 describe the request. Fix it instead.
        if r.status_code != 429 and r.status_code < 500:
            r.raise_for_status()
        reset = r.headers.get("x-ratelimit-reset")
        if reset is not None:
            delay = float(reset)          # requests/min or tokens/min limit
        else:
            delay = min(2 ** attempt, 30) # concurrency 429 and 5xx: no reset header
        time.sleep(delay + random.uniform(0, 1))
    r.raise_for_status()
```

## クレジット残高がなくなった場合

クレジット残高がゼロになると、リクエストはブロックされ `402 Payment Required` が返されます。残高は [クレジットページ](https://kiln.bricksum.com/app/credits)で確認してください。

ステータスコードの全一覧は、 [エラー](https://kiln.bricksum.com/docs/ja/errors) を参照してください。