# レート制限
> 2 段階の固定ウィンドウ制限、X-RateLimit レスポンスヘッダー、429 の処理。

REST API（`/v1`）へのリクエストは 2 段階の固定ウィンドウカウンターでレート制限され、**いずれか一方でも超過すると 429** になります：

| レベル | 上限 | ウィンドウ |
| --- | --- | --- |
| アカウント単位 | 600 回/分 | 60s |
| API key 単位 | 120 回/分 | 60s |

これらの上限はプラットフォーム共通の設定です。すべてのアカウント、すべての API key に同じ上限が適用され、アカウントごとには設定されません。

## レスポンスヘッダー

以下のヘッダーは `429`（`rate_limited`）レスポンスにのみ含まれ、成功レスポンスには含まれません：

| Header | 説明 |
| --- | --- |
| `Retry-After` | リトライまでに待つ秒数 |
| `X-RateLimit-Limit-Tenant` / `X-RateLimit-Remaining-Tenant` | アカウント単位の上限 / 残り |
| `X-RateLimit-Limit-Key` / `X-RateLimit-Remaining-Key` | key 単位の上限 / 残り |
| `X-RateLimit-Reset` | 上限がリセットされるまでの秒数 |

## 429 の処理

```json
{
  "error": {
    "code": "rate_limited",
    "type": "rate_limit_error",
    "message": "Tenant rate limit exceeded",
    "retryable": true,
    "details": {
      "scope": "tenant",
      "limit": 600,
      "window_seconds": 60,
      "retry_after_seconds": 12
    },
    "request_id": "req_..."
  }
}
```

`details.scope` は超過したレベル（`tenant` または `api_key`）、`details.limit` はそのレベルの上限です。`details.retry_after_seconds` は `Retry-After` ヘッダーと同じ値です。`tenant` はアカウント全体、`api_key` はそのキー 1 本を指します。

- 429 の `Retry-After` ヘッダー（秒）に従って待ち、**同一の** `Idempotency-Key` でリトライします
- レート制限の最も一般的な原因はバースト的な同時リクエストです。クライアント側でリクエストを平準化してください
- 上限の引き上げが必要な場合：コンソールからお問い合わせいただくか、担当のアカウントマネージャーにご連絡ください