supabase-rate-limits

Supabase のレート制限

概要

Supabase は、PostgREST、Auth、Storage、Realtime、Edge Functions のすべての API サーフェスでレート制限とクォータを適用しており、数値はプランの階層によって異なります。このスキルでは、階層ごとの正確な制限、Supavisor によるコネクションプーリング、リトライ／バックオフとページネーションのパターン、ダッシュボードでの監視について説明します。クォータの範囲内に収め、429 エラーを適切に処理できます。

前提条件

• 有効な Supabase プロジェクト（いずれのプランでも可）
• @supabase/supabase-js v2 以降がインストール済み
• プロジェクト URL と anon／service-role キーが利用可能
• Node.js 18 以降、または同等のランタイム

手順

ステップ 1 — プランの制限を確認する

レート制限はサーフェスやプランによって異なります。主な API 制限は次のとおりです。

指標	Free	Pro	Enterprise
1 分あたりのリクエスト数（RPM）	500	5,000	無制限（カスタム）
1 日あたりのリクエスト数（RPD）	50,000	1,000,000	無制限（カスタム）

Auth、Storage、Realtime、Edge Functions、Database の接続には、それぞれ独自のクォータがあります。設計を始める前に、rate-limit-tiers.md でサーフェスごとの制限の全容を確認してください。

ステップ 2 — Supavisor でコネクションをプールする

Supavisor は Supabase に組み込まれたコネクションプーラー（PgBouncer に代わるもの）です。ワークロードに応じてモードを選択してください。

用途	モード	ポート
サーバーレス／Edge Functions	トランザクション	6543
Next.js API ルート	トランザクション	6543
長時間実行するワーカー	セッション	5432
Realtime サブスクリプション	直接接続（プーラーなし）	5432
Prisma／Drizzle ORM	トランザクション + ?pgbouncer=true	6543

トランザクションモード（ポート 6543）では、各トランザクションの後にコネクションがプールへ返されるため、サーバーレスに適した標準設定です。セッションモード（ポート 5432）では、LISTEN/NOTIFY とプリペアドステートメント用に専用コネクションを保持します。クライアントの完全なセットアップと接続文字列の形式については、implementation.md を参照してください。

ステップ 3 — リトライ、ページネーション、バッチ処理を行う

429 エラーとプール枯渇を認識する指数バックオフのリトライで、クエリをラップします。

// Retryable when the error is a rate limit, "too many requests",
// code 429, or PGRST000 (connection pool exhausted). Delay doubles
// per attempt with jitter, capped at maxDelayMs, honoring Retry-After.
const users = await withRetry(() =>
  supabase.from('users').select('id, email, created_at').eq('active', true)
)

次に、リクエスト量を 2 つの方法で減らします。大きな読み取りには .range(from, to) を使ってページネーションを適用し、レスポンスを小さく保ってタイムアウトを回避します。また、N 件の書き込みを 1 回のバッチ upsert にまとめます（1 リクエストあたり最大約 1000 行。これを超えるデータは分割してください）。withRetry、fetchPaginated、バッチ／chunk ヘルパーの全容と、ダッシュボードでの監視手順については、implementation.md を参照してください。

出力

このスキルを適用すると、次の状態になります。

• プランごとのレート制限を明確に把握できます（Free：500 RPM／50K RPD、Pro：5K RPM／1M RPD）
• Supavisor によるコネクションプーリングが設定されます（サーバーレス向けのトランザクションモード、ポート 6543）
• 429 エラーを処理する指数バックオフ付きのリトライラッパーが用意されます
• .range(0, 99) を使ったページネーション付きクエリで、ペイロードサイズを削減できます
• バッチ upsert パターンにより、N 件のリクエストを 1 件に削減できます
• API 使用状況のアラートを監視するダッシュボードが設定されます

エラー処理

エラー	原因	解決策
429 Too Many Requests	RPM または RPD の上限を超過しました	withRetry によるバックオフを適用します。同時実行数を減らすか、プランをアップグレードします
PGRST000: could not connect	接続プールが枯渇しています	Supavisor のトランザクションモード（ポート 6543）に切り替えます。同時クエリ数を減らします
認証の over_request_rate_limit	1 つの IP からのサインアップまたはログインが多すぎます	CAPTCHA を追加します。ダッシュボードでカスタム認証レート制限を設定します
Storage の 413 Payload Too Large	ファイルがプランの上限を超えています	TUS の再開可能なアップロードを使用します。プランのファイルサイズ上限を確認します
Realtime の too_many_connections	同時接続数の上限に達しました	使用していないチャンネルの登録を解除します。500 接続が可能な Pro にアップグレードします
Edge Function の BOOT_ERROR	コールドスタートのタイムアウト、またはメモリ超過です	バンドルサイズを小さくします。トップレベルで大きなインポートを避けます
Prisma での pgbouncer=true エラー	接続文字列パラメーターが不足しています	ポート 6543 のプーラー接続文字列に ?pgbouncer=true を追加します

レート制限のレスポンスヘッダー（X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset、Retry-After）と、それぞれへの対処方法については、errors.md を参照してください。

例

• バッチ挿入に対応し、レート制限に安全なクライアントを備えたサーバーレス Edge Function — examples.md を参照してください
• ランタイムごとの接続文字列の選択（サーバーレス、長時間稼働、直接接続）— examples.md を参照してください
• キューベースのスロットリングとクライアント側でのヘッダー監視 — examples.md を参照してください

リソース

• Supabase プラットフォームの上限とクォータ
• Supavisor 接続プーリング
• Edge Functions の上限
• Storage の上限
• @supabase/supabase-js リファレンス

次のステップ

RLS ポリシーと API キー管理を使用した Supabase プロジェクトの保護については、supabase-security-basics を参照してください。データベースクエリとインデックスの最適化については、supabase-performance-tuning を参照してください。