supabase-rate-limits

Supabase Rate Limits

Overview

Supabase enforces rate limits and quotas across every API surface — PostgREST, Auth, Storage, Realtime, and Edge Functions — and the numbers scale by plan tier. This skill gives you the exact per-tier limits, connection pooling via Supavisor, retry/backoff and pagination patterns, and dashboard monitoring so you stay within quota and handle 429 errors gracefully.

Prerequisites

• Active Supabase project (any tier)
• @supabase/supabase-js v2+ installed
• Project URL and anon/service-role key available
• Node.js 18+ or equivalent runtime

Instructions

Step 1 — Know your tier limits

Rate limits differ per surface and per plan. The headline API limits:

Auth, Storage, Realtime, Edge Functions, and Database connections each carry their own quotas. See the full per-surface breakdown in rate-limit-tiers.md before you architect.

Step 2 — Pool connections with Supavisor

Supavisor is Supabase's built-in connection pooler (replaced PgBouncer). Pick the mode by workload:

Transaction mode (port 6543) returns a connection to the pool after each transaction — the right default for serverless. Session mode (port 5432) holds a dedicated connection for LISTEN/NOTIFY and prepared statements. Full client setup and connection-string formats are in implementation.md.

Step 3 — Retry, paginate, and batch

Wrap queries in an exponential-backoff retry that recognizes 429s and pool exhaustion:

// 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)
)

Then cut request volume two ways: paginate large reads with .range(from, to) so responses stay small and avoid timeouts, and collapse N writes into one batch upsert (max ~1000 rows/request, chunk larger sets). The full withRetry, fetchPaginated, and batch/chunk helpers — plus dashboard monitoring steps — are in implementation.md.

Output

After applying this skill you will have:

• Clear understanding of rate limits per tier (Free: 500 RPM / 50K RPD, Pro: 5K RPM / 1M RPD)
• Connection pooling configured via Supavisor (port 6543 transaction mode for serverless)
• Retry wrapper with exponential backoff handling 429 errors
• Paginated queries using .range(0, 99) to reduce payload size
• Batch upsert pattern reducing N requests to 1
• Dashboard monitoring configured for API usage alerts

Error Handling

Rate-limit response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After) and how to act on each are in errors.md.

Examples

• Serverless Edge Function with a batch-inserting, rate-limit-safe client — see examples.md
• Connection-string selection per runtime (serverless vs long-running vs direct) — see examples.md
• Queue-based throttling and client-side header monitoring — see examples.md

Resources

• Supabase Platform Limits & Quotas
• Supavisor Connection Pooling
• Edge Functions Limits
• Storage Limits
• @supabase/supabase-js Reference

Next Steps

For securing your Supabase project with RLS policies and API key management, see supabase-security-basics. For optimizing database queries and indexing, see supabase-performance-tuning.