Your Next.js route calls OpenAI or Anthropic and gets a 429. The usual advice is to add a retry with backoff. That fixes some 429s and makes others worse, because both providers now use the same status for problems that clear in a second and problems that won't clear until someone changes a billing setting. This post shows how to tell them apart from the error code, what the official SDKs do by default, and a small helper that retries rate limits and overload but stops on the billing codes it knows.

Checked 17 Oct 2026 with openai 7.36.0 and @anthropic-ai/sdk 0.135.0 (Node 20.19, TypeScript strict). Error codes and their meanings come from the OpenAI and Anthropic docs, quoted below and listed in Sources. Providers add codes from time to time, so check the docs against the date above.

What we did and didn't test. We didn't trigger a real 429. We ran both SDKs against a local mock server that returns error bodies and headers we rebuilt from the docs, so the bodies are our reconstruction, not captured failures. What the mock does show is real SDK behaviour: the error class each SDK throws, which fields it fills in, how many requests it sends with its default retries, and how it handles retry-after. Our helper type-checks with tsc --strict and has 20 unit tests. We aren't affiliated with or endorsed by OpenAI or Anthropic; their product and model names are their trademarks, used here only to identify them.

Quick answer: read the code, not the status

A 429 on its own doesn't tell you what to do. Look one level down:

• OpenAI: read error.code. The error codes guide says: "For billing-related errors, inspect error.code to identify the specific cause. The broader error.type can still be insufficient_quota."
• Anthropic: read the error type, and check error.details.error_code for a spend cap.

Then split the result into two groups:

1. Can clear by waiting: rate limits, ramp-up limits and overload. Retry a few times, honouring Retry-After.
2. Won't clear by waiting: credits, quota and spend limits. OpenAI is direct about it: "Retrying billing, spend, or quota errors won't restore API access. Update the relevant credits or limits before sending another request." Stop, log it and show the user a clear message.

The OpenAI 429s

The OpenAI error codes guide lists several 429 causes. Here they are with what each one likely needs from you:

The two organization codes are too long for a table cell:

organization_spend_limit_exceeded
organization_usage_limit_exceeded

Two of these can surprise you:

• slow_down can appear under your limits. The guide says it "can occur even when your traffic is within its requests-per-minute and tokens-per-minute limits." It's about how fast your traffic grows. As a rule of thumb, once traffic reaches 1 million input tokens per minute, the guide suggests you "increase it by no more than 50% every 15 minutes."
• A 429 on your first request is unlikely to be a rate limit. It's more likely one of the billing codes, which share the 429 status. Check error.code before you add retries.

Overload isn't a 429 on OpenAI. The guide lists "503 - Model temporarily overloaded" with code server_is_overloaded, and notes that "Video overload, for example, now returns 503 where it previously returned 429." If your handler only catches rate-limit errors, it may miss this one.

OpenAI also sends rate-limit headers on responses. The rate limits guide lists these, among others:

retry-after
x-ratelimit-limit-requests
x-ratelimit-remaining-requests
x-ratelimit-reset-requests
x-ratelimit-limit-tokens
x-ratelimit-remaining-tokens
x-ratelimit-reset-tokens

The same guide warns that Retry-After "does not mean that quota, billing, or other errors that require user action can be resolved by retrying."

The Anthropic 429, 529 and the spend-limit 400

Anthropic's errors page describes one 429 type that covers several causes:

429 - rate_limit_error: Your organization has hit a rate limit, reached its usage tier's monthly spend cap, or reached a spend limit on the Claude Code workspace. A tier spend-cap 429 has no retry-after header and keeps failing until access resumes

The rate limits page explains how to tell the spend cap apart: on the Messages API, error.details.error_code is enforced_spend_limit_reached. A real rate limit names the limit you hit (requests, input tokens or output tokens per minute), and "When the response has a retry-after header, wait that many seconds before retrying."

Three more cases are worth handling:

The 400 one is easy to miss. The errors page says: "The API also returns a 400 when usage reaches an organization or workspace spend limit you set." It won't show up in a 429 handler at all.

The errors page also mentions acceleration limits: "if your organization has a sharp increase in usage, you might see 429 errors because of acceleration limits on the API. To avoid hitting acceleration limits, ramp up your traffic gradually and maintain consistent usage patterns."

Anthropic's rate-limit headers have longer names, for example:

retry-after
anthropic-ratelimit-requests-limit
anthropic-ratelimit-requests-remaining
anthropic-ratelimit-requests-reset
anthropic-ratelimit-input-tokens-remaining

What the SDKs do by default (our mock test)

Both SDKs retry for you. The OpenAI SDK README says: "Certain errors will be automatically retried 2 times by default, with a short exponential backoff." It lists "429 Rate Limit, and >=500 Internal errors" among them. Anthropic's errors page says the SDK "automatically retries transient failures (such as connection errors, rate limits, and 5xx server errors) with exponential backoff, twice by default, honoring the retry-after header when present."

We counted the requests our mock server received. These are the results from our run:

• Every 429 arrived as RateLimitError in both SDKs, including the credit, quota and spend-limit bodies. The class alone doesn't tell you whether to retry.
• With default settings, the mock received 3 requests for every 429, 503 and 529 body, including insufficient_quota and credit_balance_exhausted as well as the spend-limit codes and Anthropic's spend cap. So by default each failed user action can cost three calls that the docs say won't succeed. The Anthropic 400 got 1 request.
• With maxRetries: 0, the mock received exactly 1 request for every case.
• OpenAI 503 and Anthropic 529 arrived as InternalServerError, not RateLimitError. The Anthropic 400 arrived as BadRequestError.
• retry-after: 1 produced gaps of about one second in both SDKs.
• retry-after: 120 was handled differently. openai 7.36.0 retried after about half a second and one second, so it didn't wait the 120 seconds. We didn't check whether that's a deliberate limit in the SDK; either way, don't rely on it to honour long waits. @anthropic-ai/sdk 0.135.0 waited over two minutes before each retry, so the call took about five minutes to fail. In a serverless route, a wait that long may hit your function timeout first.
• Where the code lives differs. In openai, err.code and err.type were set (for example project_spend_limit_exceeded and insufficient_quota). In @anthropic-ai/sdk, err.code was empty, and the type and details were inside err.error.error.

Our mock bodies are reconstructions, and real responses can differ. The SDK behaviour above is what the code did with those bodies.

One classifier for both SDKs

This helper reads both SDKs' errors and returns what to do. It looks at spend and billing codes first, so a billing 429 with one of these codes is never treated as a rate limit. A code added later would be treated as a rate limit and retried within the caps, so check the docs for new codes:

// lib/provider-error.ts
export type ProviderErrorKind =
  | "rate_limit" | "overloaded" | "quota_or_billing" | "spend_limit" | "other";
export type Classified = {
  kind: ProviderErrorKind; retryable: boolean;
  retryAfterMs: number | null; code: string | null;
};

const BILLING = new Set(["insufficient_quota", "credit_balance_exhausted",
  "organization_usage_limit_exceeded"]);
const SPEND = new Set(["project_spend_limit_exceeded",
  "organization_spend_limit_exceeded", "enforced_spend_limit_reached"]);
const SPEND_400 = "You have reached your specified"; // Anthropic 400 prefix

type Headersish = { get(name: string): string | null } | undefined;
const str = (v: unknown) => (typeof v === "string" ? v : null);

export function parseRetryAfter(h: Headersish, now = Date.now()): number | null {
  const ms = h?.get("retry-after-ms");
  if (ms && Number.isFinite(Number(ms))) return Math.max(0, Number(ms));
  const v = h?.get("retry-after");
  if (!v) return null;
  const s = Number(v);
  if (Number.isFinite(s)) return Math.max(0, s * 1000);
  const d = Date.parse(v); // HTTP-date form
  return Number.isNaN(d) ? null : Math.max(0, d - now);
}

export function classifyProviderError(err: unknown): Classified {
  const e = (err ?? {}) as Record<string, unknown>;
  const status = typeof e.status === "number" ? e.status : undefined;
  const h = e.headers instanceof Headers ? e.headers : undefined;
  const body = (e.error ?? {}) as Record<string, unknown>;
  const inner = (body.error ?? body) as Record<string, unknown>; // Anthropic nests it
  const details = (inner.details ?? {}) as Record<string, unknown>;
  const code = str(details.error_code) ?? str(e.code) ?? str(inner.code);
  const type = str(e.type) ?? str(inner.type);
  const message = str(inner.message) ?? "";
  const retryAfterMs = parseRetryAfter(h);
  const out = (kind: ProviderErrorKind, retryable: boolean): Classified =>
    ({ kind, retryable, retryAfterMs: retryable ? retryAfterMs : null, code: code ?? type });

  if (code && SPEND.has(code)) return out("spend_limit", false);
  if (status === 400 && message.startsWith(SPEND_400))
    return out("spend_limit", false);
  if ((code && BILLING.has(code)) || type === "insufficient_quota")
    return out("quota_or_billing", false);
  if (status === 429) return out("rate_limit", true);
  if (status === 529 || status === 503 || type === "overloaded_error")
    return out("overloaded", true);
  return out("other", false);
}

The docs don't give a separate code for the Anthropic spend-limit 400, but the rate limits page says its message begins "You have reached your specified API usage limits" or "You have reached your specified workspace API usage limits". So the helper treats a 400 with that opening as spend_limit, not retryable, and the route below stops and returns the same message as for billing errors. If Anthropic rewords the message, it would fall back to other.

A capped retry that stops on known billing errors

Turn the SDK's own retries off with maxRetries: 0, so you don't stack two retry loops, and use one you control. This one caps attempts, caps each wait and the total wait, honours Retry-After inside those caps, and gives up straight away on anything not retryable:

// lib/provider-retry.ts
import { classifyProviderError } from "./provider-error";

export async function withProviderRetry<T>(
  fn: () => Promise<T>,
  { maxAttempts = 3, maxTotalWaitMs = 20_000, maxSingleWaitMs = 10_000 } = {},
): Promise<T> {
  const attempts = Math.min(maxAttempts, 5);
  let waited = 0;
  for (let attempt = 1; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const c = classifyProviderError(err);
      if (!c.retryable || attempt >= attempts) throw err;
      const backoff = 500 * 2 ** (attempt - 1) * (1 - Math.random() * 0.25);
      const wait = c.retryAfterMs ?? backoff;
      // A Retry-After longer than our caps means "not now": fail fast.
      if (wait > maxSingleWaitMs || waited + wait > maxTotalWaitMs) throw err;
      waited += wait;
      await new Promise((r) => setTimeout(r, wait));
    }
  }
}

In our unit tests, a billing or spend error led to one call and no wait. A rate limit with retry-after: 1 led to three calls with two one-second waits. A retry-after: 120 failed at once without sleeping, and a 529 with no header backed off at 500 ms and then 1 s.

Pick the caps to fit your route's timeout. If your platform stops functions after a set time, keep the total wait well under it.

Wiring it into a Next.js route

The route takes the user id from the auth session, never from the request body, and returns a status your UI can act on:

// app/api/chat/route.ts
import { createHash } from "node:crypto";
import OpenAI from "openai";
import { createClient } from "@/lib/supabase/server";
import { classifyProviderError } from "@/lib/provider-error";
import { withProviderRetry } from "@/lib/provider-retry";

const openai = new OpenAI({ maxRetries: 0 }); // our helper does the retrying

export async function POST(req: Request) {
  const supabase = await createClient();
  const { data: auth } = await supabase.auth.getClaims();
  const userId = auth?.claims.sub; // from the verified session only
  if (!userId) return Response.json({ error: "Sign in first" }, { status: 401 });
  // OpenAI gets a hash, not the raw id
  const safetyId = createHash("sha256").update(userId).digest("hex");

  const { message } = (await req.json()) as { message: string };
  try {
    const res = await withProviderRetry(() =>
      openai.responses.create({
        model: process.env.OPENAI_MODEL!,
        input: message,
        safety_identifier: safetyId,
      }),
    );
    return Response.json({ text: res.output_text });
  } catch (err) {
    const c = classifyProviderError(err);
    console.error("provider error", { userId, kind: c.kind, code: c.code });
    if (c.kind === "rate_limit" || c.kind === "overloaded") {
      const secs = Math.ceil((c.retryAfterMs ?? 5_000) / 1000);
      return Response.json({ error: "Busy, try again shortly" },
        { status: 503, headers: { "Retry-After": String(secs) } });
    }
    if (c.kind === "quota_or_billing" || c.kind === "spend_limit") {
      return Response.json({ error: "AI is unavailable right now" }, { status: 503 });
    }
    return Response.json({ error: "Something went wrong" }, { status: 500 });
  }
}

A few choices here are deliberate:

• Your users get a 503, not the provider's 429. A 429 from your route should mean "this user is sending too much". When the provider is the problem, that's a service issue on your side.
• Known billing errors are logged, not retried, and the message doesn't expose your account state to users. Alert yourself on quota_or_billing and spend_limit.
• OpenAI gets a hash of the user id, not the raw id. OpenAI suggests hashing the identifier you send, so we pass a SHA-256 hash of the user id as safety_identifier.
• The same pattern works for Anthropic. Create the Anthropic client with maxRetries: 0 and call messages.create. The classifier already reads the nested Anthropic error.

Why one user can cause 429s for everyone

OpenAI's error codes guide says that "limits are applied per organization and not per user." Anthropic's limits are also set at the organization level. If one signed-in user scripts your chat route, they use up the shared requests and tokens per minute, and every other user starts seeing errors.

Retries don't help with that. What helps is a limit per user in your own app, keyed on the session user id, so one account can't use up the shared allowance. Our per-user spend limits post walks through a per-user rate limit and a monthly dollar cap in Supabase.

Reduce rate-limit pressure with prompt caching

On Anthropic, cached reads can take pressure off your input-token limit. The rate limits page says: "For most Claude models, only uncached input tokens count toward your ITPM rate limits." If your prompts share a long prefix, getting caching to work can leave more room under that limit. Our prompt caching post covers how to check whether requests actually hit the cache.

Checklist

• Read error.code (OpenAI) or the type and details.error_code (Anthropic) before deciding to retry.
• Never retry credit, quota or spend-limit errors. Alert on them.
• Set maxRetries: 0 on the SDK if you run your own retry loop, so the two don't stack.
• Cap attempts, each wait and the total wait. Honour Retry-After only within those caps.
• Handle OpenAI 503 and Anthropic 529 as overload, and the Anthropic spend-limit 400 as not retryable.
• Take the user id from the session, and limit each user so one account can't exhaust the organization's limits.

Related

• OpenAI and Anthropic spend limits per user in Next.js: a per-user rate limit and a monthly dollar cap in Supabase.
• Prompt caching not working? Check it in OpenAI and Anthropic (Next.js): how to confirm cache hits and price cached tokens.

Sources (checked 17 October 2026):

• OpenAI: Error codes
• OpenAI: Rate limits
• OpenAI Node SDK README (Retries)
• Anthropic: Errors
• Anthropic: Rate limits
• Anthropic TypeScript SDK

Disclosure: we make this. Our free AI API cost calculator estimates per-call spend before you retry: https://edtrackai.github.io/tools/ai-api-cost-calculator?utm_source=hashnode&utm_medium=article&utm_campaign=sprint1&utm_content=e57-openai-anthropic-429-rate-limit-error-nextjs

Row Level Security is switched on. Every table has a policy. The policies mention auth.uid(). A reviewer skims the migration, sees all three, and approves it. And one signed-in user can still read every other user's row.

This post covers two patterns like that. Both came from readers of our earlier Dev.to article, 7 security bugs AI agents write in Next.js + Supabase + Stripe apps, and both are easy to miss because they look right:

1. A policy that checks the user is signed in, but not that the row is theirs.
2. A free-credit grant that treats a new account as a new person, which Gmail dot and plus aliases get around.

All the SQL below was run on a local PostgreSQL 17 database with a stand-in auth.uid() function. Supabase behaviour is quoted from the Supabase RLS docs, checked on 15 October 2026. This site isn't affiliated with Supabase.

The policy that checks you're logged in, not that the row is yours

cekuu35 pointed this out in the comments. Our article suggested sweeping for qual = 'true', and they noted that's only the first pass. Once an agent is told not to write using (true), it tends to write this instead:

create policy "Users can view profiles"
  on public.profiles for select
  to authenticated
  using (auth.uid() is not null);

It reads well. RLS is on, there's a policy, and the policy mentions auth. A qual = 'true' check won't flag it, because the expression isn't literally true.

But look at what it actually tests. auth.uid() is not null is true for every signed-in user, on every row. Nothing ties the row to the person asking. So any logged-in user can query the table with the anon/publishable key and get everyone's email, stripe_customer_id, and whatever else is in the table. One line in the browser console is enough:

await supabase.from('profiles').select('*')

In our local test, a signed-in user with this policy saw 2 of 2 rows, including the other user's.

The policy is only correct when the table really is meant to be readable by every logged-in user, like a public directory. For anything per-user, it's a leak.

Why reviews and linters miss it

The usual checks all pass:

• RLS enabled? Yes.
• A policy exists for each operation? Yes.
• No using (true)? Correct, there isn't one.
• Mentions auth.uid()? It does.

None of those ask the question that matters: does the expression compare the row's owner column to the caller? The Supabase docs show the owner-scoped shape for every operation. For select it's:

using ( (select auth.uid()) = user_id )

Insert uses the same comparison in with check. The docs also point out that auth.uid() returns null for unauthenticated requests. That's why a not-null test feels like a security check. It does stop signed-out users, but it stops nobody else.

Find these policies with pg_policies

Postgres exposes every policy in the pg_policies view. qual holds the USING expression and with_check holds the WITH CHECK expression, both as text. This query lists policies in public where either expression doesn't compare auth.uid() to something with =. That catches bare true, auth.uid() is not null, and anything else that never ties the row to the caller:

select schemaname, tablename, policyname, cmd, roles, qual, with_check
from pg_policies
where schemaname = 'public'
  and (
       (qual is not null
        and qual !~* 'auth\.uid\(\)[^=]*=|=[^=]*auth\.uid\(\)')
    or (with_check is not null
        and with_check !~* 'auth\.uid\(\)[^=]*=|=[^=]*auth\.uid\(\)')
  );

Run it in the Supabase SQL editor. On our test database, it returned the auth.uid() is not null select policy and a with check (true) insert policy, and 0 rows after the fix below. Postgres stores (select auth.uid()) as ( SELECT auth.uid() AS uid); the pattern allows for that.

Treat the results as a review list, not a verdict. It's a text match, so:

• Expected hits: genuinely public tables, and team tables scoped through an exists (...) membership check. Check each one and make sure it's intentional.
• What it can't see: an = that compares auth.uid() to the wrong column will pass. So will a policy that joins through an unfiltered table. The regex also passes any expression that contains a comparison somewhere, even when something else makes it broad. Both of these return 0 rows but scope nothing:

using ( auth.uid() is not null or <anything> )
using ( auth.uid() = auth.uid() )

cekuu35's comment includes their own version of the regex and a runnable red/green demo. The extra step we'd add is a two-user test: sign in as user A and try to read and update user B's row. That catches the shapes a pattern match won't.

The fix: scope USING and WITH CHECK to the owner

Replace the not-null test with a comparison against the owner column, one policy per operation the app needs:

drop policy "Users can view profiles" on public.profiles;

create policy "Owners read own profile"
  on public.profiles for select
  to authenticated
  using ( (select auth.uid()) = user_id );

create policy "Owners insert own profile"
  on public.profiles for insert
  to authenticated
  with check ( (select auth.uid()) = user_id );

create policy "Owners update own profile"
  on public.profiles for update
  to authenticated
  using ( (select auth.uid()) = user_id )
  with check ( (select auth.uid()) = user_id );

create policy "Owners delete own profile"
  on public.profiles for delete
  to authenticated
  using ( (select auth.uid()) = user_id );

Leave out the delete policy if users shouldn't delete their own rows; with RLS on, no policy means no deletes.

Some notes from the Supabase docs:

• using vs with check: using decides which existing rows a user can see or target. with check decides what a new or updated row is allowed to look like. On updates, you need both: without with check, a user could update their row and set user_id to someone else's. In our test, that reassignment failed with this error, which is what you want:

new row violates row-level security policy for table "profiles"

• The (select ...) wrapper: wrapping auth.uid() in (select ...) lets Postgres evaluate it once per statement instead of once per row. It's a performance detail, not a security one, but it costs nothing.
• to authenticated: this keeps the anon role out entirely. Signed-out requests then can't match the policy at all.

If you hit that same error on inserts after tightening policies, a common cause is .insert().select() (or an upsert): returning the new row also needs a matching select policy, so keep the select policy alongside the insert one.

Free credits and Gmail aliases: a new account isn't a new person

elijahbrown raised the second pattern in the same thread. Treating "account just created" as proof someone should get free credits doesn't hold up. Anyone can sign up again with jane.doe+2@gmail.com or j.a.n.e.doe@gmail.com and look brand new. Gmail ignores dots in the local part and everything after a +, so all of those reach the same inbox.

This isn't an RLS bug, strictly speaking. It's the same mistake, though: trusting something that looks like identity but isn't. Their suggested fix is to key the credit grant on a normalised email in a separate claims table with a unique index, and only grant the credits when that insert succeeds.

Here's a normalisation function. It lowercases every address. For gmail.com and googlemail.com it also strips dots and any +suffix from the local part, and maps both domains to gmail.com:

create or replace function public.normalize_email(addr text)
returns text
language sql
immutable
strict
as $$
  select case
    when split_part(lower(trim(addr)), '@', 2) in ('gmail.com', 'googlemail.com')
      then replace(split_part(split_part(lower(trim(addr)), '@', 1), '+', 1), '.', '')
           || '@gmail.com'
    else lower(trim(addr))
  end
$$;

It's marked immutable so it can feed a stored generated column; Postgres only allows immutable functions in generated columns. Then the claims table:

create table public.trial_claims (
  id               bigint generated always as identity primary key,
  user_id          uuid unique references auth.users (id) on delete set null,
  email            text not null,
  email_normalized text generated always as (public.normalize_email(email)) stored,
  claimed_at       timestamptz not null default now()
);

create unique index trial_claims_email_normalized_key
  on public.trial_claims (email_normalized);

alter table public.trial_claims enable row level security;
-- No policies for anon/authenticated: only your server code writes here.

There's deliberately no on delete cascade: if deleting an account also deleted its claim, the same inbox could delete, sign up again and claim a second time. With on delete set null, the claim row (and its normalised email) stays after the account is gone. The unique on user_id also stops one account claiming twice.

Grant credits only when the claim row is actually inserted:

insert into public.trial_claims (user_id, email)
values ($1, $2)
on conflict do nothing
returning user_id;

If the returning comes back empty, someone already claimed with that inbox, or this account already claimed. (on conflict do nothing with no target covers both unique checks.) In our test, Jane.Doe+x@GoogleMail.com and j.a.n.e.doe@gmail.com both normalised to janedoe@gmail.com, and the second claim inserted nothing. Because the unique index does the check, two signups racing each other can't both win.

Run the insert from server code, such as a Route Handler, Server Action, or webhook, using the email from the verified session, not one sent by the browser.

Limits worth being honest about:

• Gmail is easy; other domains aren't. Some other providers support plus addressing too, and you could extend the function, but rules vary by provider. Lowercasing everything else is the safe default.
• Disposable email domains get past this entirely. Keep the free credit small, or put larger grants behind a verified payment method.
• Store the original email too. Use the normalised one only for the uniqueness check, never as the address you send to.

A quick checklist

• Run the pg_policies query above and review every row it returns.
• Every per-user table: an owner comparison in using on select, update, and delete, and in with check on insert and update.
• to authenticated on policies that should never apply to signed-out users.
• A two-user test in CI: user A can't read or update user B's row.
• Free credits keyed on a normalised email with a unique index, granted only when the insert succeeds.

Related

• If you see permission denied for table instead, that's a missing grant, not RLS. See the Supabase Data API grants change.

Thanks to cekuu35 and elijahbrown for raising these in the comment thread.

Sources (checked 15 October 2026):

• Supabase: Row Level Security
• PostgreSQL: pg_policies
• PostgreSQL: Generated columns
• Dev.to comments by cekuu35 and elijahbrown

Disclosure: we make this. Our free Next.js + Supabase + Stripe security checker flags tables without RLS, using (true) / with check (true) write policies, anon write policies and missing grants in your migration files. It's heuristic and won't catch every policy shape above: https://edtrackai.github.io/checker?utm_source=hashnode&utm_medium=article&utm_campaign=sprint1&utm_content=e57-supabase-rls-policies-pass-review-leak-data