home / skills / jeremylongshore / claude-code-plugins-plus-skills / supabase-rate-limits

supabase-rate-limits skill

/plugins/saas-packs/supabase-pack/skills/supabase-rate-limits

This skill helps implement Supabase rate limiting with automatic retries, backoff, and idempotent requests to optimize API throughput.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill supabase-rate-limits

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

1.1 KB

---
name: supabase-rate-limits
description: |
  Implement Supabase rate limiting, backoff, and idempotency patterns.
  Use when handling rate limit errors, implementing retry logic,
  or optimizing API request throughput for Supabase.
  Trigger with phrases like "supabase rate limit", "supabase throttling",
  "supabase 429", "supabase retry", "supabase backoff".
allowed-tools: Read, Write, Edit
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# Supabase Rate Limits

## Prerequisites
- Supabase SDK installed
- Understanding of async/await patterns
- Access to rate limit headers


See `{baseDir}/references/implementation.md` for detailed implementation guide.

## Output
- Reliable API calls with automatic retry
- Idempotent requests preventing duplicates
- Rate limit headers properly handled

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources
- [Supabase Rate Limits](https://supabase.com/docs/rate-limits)
- [p-queue Documentation](https://github.com/sindresorhus/p-queue)

Overview

This skill implements Supabase rate limiting, backoff, and idempotency patterns to make API calls resilient and predictable. It provides retry logic that respects Supabase rate-limit headers and prevents duplicate side-effecting operations. Use it to reduce 429 errors, avoid wasted work, and keep throughput within allowed limits.

How this skill works

The skill inspects Supabase response headers (rate-limit, remaining, reset) and adapts request pacing accordingly. It applies exponential backoff with jitter for transient 429/5xx errors, uses idempotency keys for write operations, and queues tasks to smooth bursts. Async/await-friendly patterns ensure retries and backoff integrate cleanly with existing async Python code.

When to use it

When your app receives intermittent 429 (Too Many Requests) responses from Supabase.
When you need safe retries for operations that must not be duplicated (create/update/delete).
When coordinating high-throughput clients or background jobs against Supabase APIs.
When you want to respect Supabase rate-limit headers to avoid throttling and service disruption.
When implementing client libraries or microservices that require robust API reliability.

Best practices

Read and honor Supabase rate-limit and reset headers instead of hard-coded delays.
Use idempotency keys for any non-idempotent write to prevent duplicate side effects on retry.
Prefer exponential backoff with random jitter to avoid synchronized retry storms.
Limit concurrent requests with a queue or semaphore when bursts can exceed limits.
Log retry attempts and final failure reasons for observability and tuning.

Example use cases

A serverless function that retries transient insert failures while ensuring a single record is created using an idempotency key.
A background worker processing a job queue that paces Supabase updates by reading remaining/request-reset headers.
A client SDK wrapper that automatically applies exponential backoff for 429/5xx errors and surfaces clear retry metrics.
An integration that batches reads and throttles concurrent requests to stay below per-minute rate limits.
A migration script that retries with backoff and avoids duplicate writes across restarts.

FAQ

What headers should I watch for?

Inspect rate-limit, rate-limit-remaining, and rate-limit-reset where provided. Use remaining to throttle and reset to schedule the next attempt.

How do idempotency keys work here?

Attach a stable idempotency key to write requests so retries can be deduplicated server-side or by your middleware to prevent duplicate operations.