API rate limit exceeded

Your AI feature worked all week, and now half the calls come back with an error and the logs are full of 429s. Nobody changed the code, and the dashboard says you are nowhere near your usage cap.

An API rate limit exceeded is the provider telling you that your key sent more calls in a short window than it allows, so it refused the extra ones until the window resets. The fix is rarely a bigger plan. It is finding which part of your app sends the calls, slowing that part down on purpose, and letting the rest through.

Why this is harder than it sounds

The error message names the symptom and hides the cause. The message says a limit was crossed, but not which part of your app crossed it, and that part is what you need to find.

Four things make it harder to pin down than it looks:

• One key, many features. Chat, embeddings, a reranker and tool calls often share a single provider key, so a busy feature can use up the limit and block a quiet one that sent few calls.
• One click, many calls. An agent that searches, reads, summarizes and answers turns a single user action into a burst of provider calls, and that burst is what trips the limit.
• Traffic you forgot about. Health checks, status polling, synthetic monitoring and background jobs send calls on a timer, whether anyone is using the app or not.
• Third-party integrations. A plugin, a no-code automation or a connected tool can call the same API with your key and add load you cannot see in your own code.

Limits also come in more than one shape. Providers can count calls per minute, tokens per minute, or calls per day, and the window that ran out decides how long you wait.

Raising your plan sometimes does nothing for the same reason. If an agent loop fires a whole burst of calls at once, a higher limit only delays the moment the calls start to fail.

Treat the limit as a fixed budget for your whole app, and decide on purpose which features get to spend it first. The steps below follow from that.

What it actually looks like

You will recognize an API rate limit exceeded problem by its timing more than by the message. The error shows up in bursts, and often clears on its own before you can reproduce it.

The common signs:

• Calls fail in clusters, then succeed again a short while later without any change on your side.
• The error appears at busy hours or right after a deploy, when caches are cold and every page fetches at once.
• A background job and a user-facing feature fail together, because they share one key.
• Retries make it worse. Each failure triggers more calls, and the error rate climbs instead of settling.
• Your provider dashboard shows modest total usage, because the limit counts calls per short window, not per month.
• One user with a browser extension, or a tab left polling, appears in the logs far more often than anyone else.

What happens when you exceed a rate limit

The provider rejects the call before doing any work, so you are usually not charged for it, and nothing in the request is saved. Most providers answer with a 429 Too Many Requests status, a short message, and often a header that says how long to wait.

Some APIs also send headers showing how many calls remain in the current window. Your app can read those headers and slow down before the count hits zero, instead of reacting after the error arrives.

The 429 Too Many Requests status

The 429 Too Many Requests status is the standard HTTP way of saying "slow down". A few APIs use other codes for the same thing, such as a 403 with a message about quotas, so check the body of the error and not only the code.

An oversized cookie header or a misbehaving proxy can also produce errors that look like limit problems. If only one browser or one network sees the error, suspect the client before the provider.

API rate limit exceeded, step by step

The order matters here. Each step narrows the cause, so skipping ahead tends to fix the wrong thing.

1. Read the error and its headers

Capture the full response the next time a limit error appears, including the status, the body and every header. The body usually names which limit ran out, such as calls or tokens, and a retry header tells you how long to wait.

Write down which feature made the call and at what time. Without that, every later step is guesswork.

2. Find what is sending the calls

Count calls per feature, per route and per user for the hour before the errors. In most AI apps the answer is surprising: an agent step that loops, a summary that runs on every page load, or a status check left on a short timer.

Check these in particular:

• health checks and uptime monitors that call the real API instead of a cheap endpoint
• polling loops that ask for a result every second instead of waiting for it
• browser extensions or open tabs that refresh in the background
• scheduled jobs that all start at the top of the hour
• third-party integrations that share your key

If you build through an agent such as Claude Code or Cursor, ask it to list every place in the codebase that calls the provider and what triggers each one. The list of call sites alone often shows the culprit.

3. Retry with growing waits, route by route

A retry is the right answer to an occasional limit error. Wait before trying again, double the wait each time, add a little randomness so many clients do not retry in step, and stop after a few attempts.

Respect the retry header when the provider sends one. The provider knows its own window better than your guess does.

Never retry errors that will not change on their own, such as a bad request or an invalid key. Retrying those only spends more of your limit on calls that are certain to fail.

A single retry rule for the whole app is a common mistake, because routes fail differently and need different handling:

• Batch embeddings job. Retry with long waits, because nobody is watching it in real time.
• Live chat. Retry once or twice with short waits, then show the user a clear message instead of a spinner that never ends.
• Login and form endpoints. Retry rarely or not at all, because these endpoints often carry tighter limits and repeated attempts can look like abuse.
• Agent tool calls. Cap the number of calls per run, so one runaway loop cannot use up the budget for everyone.

4. Queue sustained work instead of retrying it

Retries recover from short spikes. A queue handles steady pressure, such as indexing every document in a library or generating images for a whole catalog.

A queue holds the jobs and lets a worker send them at a pace below your limit. The trade-off is time. Results arrive later, so queue the work that users do not wait on, and keep live features out of the queue.

5. Cut the calls you do not need

Cache answers that do not change, batch small requests into fewer large ones where the API supports it, and stop work early when the user leaves the page.

Shorter prompts help too when the limit counts tokens. The prompt is where most of the trimming happens. The guide to the chat completions API walks through how each call is built.

6. Split the load when you have outgrown one key

When the app needs more throughput than one key allows, split the work. Separate keys per feature, or per project, keep a busy background job from blocking live traffic.

You can go further and spread work across accounts or regions. Spreading load across accounts is an architecture decision, so make it after the earlier steps, not instead of them.

The step people skip

Most fixes stop once the errors go away. The step that keeps them away is watching the pressure build, so you act before users notice anything.

• Separate the failures. Show retriable failures, like limit errors and timeouts, apart from failures that will never succeed, so a spike in one does not hide the other.
• Alert on retries, not only errors. A rising retry count is the early warning, because retries succeed without showing an error until they stop succeeding.
• Alert on queue depth. A queue that grows faster than it drains means you are sending work faster than your limit allows.
• Plan the way back. If you move traffic to a backup provider during an outage, write down the rule for moving it back once the main one recovers.

All of this needs a log of every call: which feature made it, which model it used, whether it succeeded, and how long it took. Most teams have that scattered across print statements, or not at all.

Supagen is the backend for AI features and agents: small teams and solo founders keep prompts, model choice and routing, and call logging out of their code and call every model, from text to image, video and speech, through one API.

Your app reaches Supagen with an ordinary HTTPS request signed by a workspace API key, so Supagen works from any language and from any agent that can make a web request. Supagen also lets a workspace add its own provider API keys, and the provider then bills that workspace directly. If you are new to keys, our guide on how to use an API key walks through it.

Comparing your options

If cost is the real pressure behind the switch, our comparison of the cheapest LLM API options is a better starting point than a higher tier.

When this is not the real problem

Sometimes the limit error is a symptom of something else, and fixing the rate does nothing.

• You are out of credit. Some providers return a limit-style error when the account balance or monthly quota is used up. The fix is billing, and no amount of waiting helps.
• The key is shared more widely than you think. An old deployment, a teammate's local script or a leaked key can be using the same quota. Rotate the key and see if the errors stop.
• The provider is down. During an outage, providers sometimes shed load with limit errors for everyone. Check their status page before rewriting your retry logic.
• The client is the problem. If one browser or one office network sees errors and nobody else does, look at proxies, extensions and oversized cookie headers first.

Run these checks before you spend a week building a queue you never needed. Go back to the steps above once you have ruled them out.

Frequently asked questions

What is an API rate limit exceeded?

An API rate limit exceeded error means your app sent more requests to an API in a set time window than the provider allows. The provider rejects the extra requests, usually with a 429 status, until the window resets.

How long does an API rate limit exceeded error last?

An API rate limit exceeded error lasts until the provider's time window resets, which depends on the limit that ran out. Check the retry header in the response, which tells you how long to wait.

Does a 429 Too Many Requests error cost me money?

A 429 Too Many Requests error usually means the provider refused the call before doing any work, so most providers do not bill it. Check your provider's billing page to confirm how it treats rejected calls.

Should I retry or queue requests after hitting the limit?

Retry when the limit errors are occasional, with growing waits between attempts. Use a queue when the pressure is steady, such as large batch jobs, and accept that queued results arrive later.

Why do I hit the limit when my usage looks low?

Rate limits count calls per short window, so a burst can cross the limit even when total monthly usage is low. In AI apps, one user action that fans out into several provider calls is the most common cause.

If you want call logs and model routing handled outside your code, you can start building free.