OpenAPI: レート制限レスポンスヘッダー

OpenAPIでのレート制限の文書化

レート制限はAPIを不正利用から保護します。レート制限ヘッダーを文書化することで、クライアントが適切なバックオフとリトライロジックを実装できます。

レート制限レスポンスヘッダー

components:
  headers:
    X-RateLimit-Limit:
      description: Maximum requests per window
      schema:
        type: integer
      example: 1000
    X-RateLimit-Remaining:
      description: Remaining requests in current window
      schema:
        type: integer
      example: 998
    X-RateLimit-Reset:
      description: Unix timestamp when the limit resets
      schema:
        type: integer
      example: 1698364800
    Retry-After:
      description: Seconds to wait before retrying (only on 429)
      schema:
        type: integer
      example: 60

レスポンスへのヘッダー適用

paths:
  /api/data:
    get:
      responses:
        '200':
          description: Success
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

レート制限ティア

認証レベル別の異なるレート制限を文書化します：

ティア	制限	ウィンドウ	認証
Anonymous	60/時	1時間	なし
Free	1,000/時	1時間	APIキー
Pro	10,000/時	1時間	APIキー
Enterprise	カスタム	カスタム	APIキー

クライアント実装ガイダンス

API説明で推奨されるクライアントの動作を説明します：

1. 各リクエスト前にX-RateLimit-Remainingを確認する
2. 429を受信した場合、Retry-Afterヘッダーを読む
3. 繰り返しの429には指数バックオフを実装する
4. リクエスト数を減らすためにレスポンスをキャッシュする