I Hit DeepSeek's Free Tier Rate Limit Mid-Project. Here's the Retry Logic I Should Have Written First.

The Error That Taught Me What "Free" Actually Means

My script had been running fine for twenty minutes. Then it just stopped, mid-batch, with a 429 error and no explanation I understood at first glance. I'd been treating DeepSeek's free-tier usage like it was unlimited, because nothing in my code suggested otherwise. Turns out that assumption was the actual bug.

I was building a small tool that processes a batch of text snippets — nothing heavy, just looping through a list and calling the API for each one. It worked fine for small batches. The first time I ran it against a few hundred items in one go, it hit a rate limit partway through and just failed. No retry, no backoff, no graceful handling. The whole batch died because of one request that got throttled.

What My Code Looked Like (The Broken Version)

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

def process_snippet(text):
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=[{"role": "user", "content": f"Summarize: {text}"}],
    )
    return response.choices[0].message.content

results = []
for snippet in snippets:
    results.append(process_snippet(snippet))

Nothing wrong with this for a handful of requests. It falls over the moment you hit any kind of rate limit, because there's no handling for it at all — one throttled request kills the whole loop.

What I Should Have Written From the Start

import time
import random
from openai import OpenAI, RateLimitError
import os

client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

def process_snippet(text, max_retries=5):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="deepseek-chat",
                messages=[{"role": "user", "content": f"Summarize: {text}"}],
            )
            return response.choices[0].message.content
        except RateLimitError:
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limited. Waiting {wait_time:.1f}s (attempt {attempt + 1}/{max_retries})")
            time.sleep(wait_time)
    raise Exception(f"Failed after {max_retries} retries")

results = []
for snippet in snippets:
    results.append(process_snippet(snippet))

Basic exponential backoff with jitter — nothing sophisticated, just enough that a single rate-limited request doesn't take down the entire batch. It waits, retries, and gives up gracefully after a fixed number of attempts instead of crashing silently.

What This Actually Fixed (and What It Didn't)

This solved the crash. It did not solve the underlying constraint, which is that the free tier has real limits on request volume and rate, and no amount of retry logic changes how much you're actually allowed to send. Retry logic just means you handle the limit gracefully instead of your script dying when you hit it. If your workload genuinely needs higher throughput than the free tier allows, backoff logic will make your batch slower, not solve the ceiling.

That's roughly where I ended up after this — not with a complaint about the free tier (it's genuinely useful for small projects and testing), but with a clearer sense of when I was outgrowing it. For anyone in that spot, wondering whether to just pay DeepSeek directly, add retry logic and stay on the free tier, or explore a usage-based alternative, it's worth actually checking the current rate limits and pricing for your specific model and volume rather than assuming — they change, and what applied when I first tested this may not hold now.

I ended up testing my batch job against a couple of different models through RouteAI, mainly because comparing throughput and cost across providers was easier with one consistent request format instead of separate free-tier limits to track for each. It didn't remove the need to handle rate limits gracefully — that's just good practice regardless of provider — but it made it faster to figure out which setup actually fit my volume.

If You're Running Into This Yourself
Add retry-with-backoff before you need it, not after a batch job dies at 2am — it costs you ten lines of code up front and saves you a debugging session later
Check your actual rate limits rather than assuming; free-tier limits vary by provider and change over time
Distinguish between "handling the limit gracefully" and "having enough throughput" — retry logic solves the first, not the second

TL;DR: DeepSeek's free tier has real rate limits, and a script with no retry logic will crash the moment it hits one. Basic exponential backoff (code above) fixes the crash, but if your actual workload needs more throughput than the free tier allows, that's a separate problem retry logic won't solve.

Linking the tool mentioned above: www.fastrouteai.com