DeepSeek API Errors and Fixes (2026): 400, 401, 402 Insufficient Balance, 422, 429, 500 and 503

DeepSeek API errors are short and easy to fix once you know what each code really means.

This guide covers every official code (400, 401, 402, 422, 429, 500 and 503), plus timeouts, “server busy” waits and the model name changes that broke many apps this year.

Everything here is checked against DeepSeek’s own error code, rate limit and change log pages as of November 2026. You also get copy-paste Python retry code.

DeepSeek API Error Codes at a Glance

DeepSeek publishes seven error codes. The table below shows each one, the cause DeepSeek gives, and whether your code should retry it.

400 Invalid Format and 422 Invalid Parameters

Both codes mean DeepSeek rejected your request before running the model. A 400 is about the shape of the body. A 422 is about the values inside it. The error message usually names the field.

Common causes of 400

• Broken JSON: a missing comma or quote in a hand-built body.
• Wrong message format: messages must be a list of objects with role and content.
• Missing reasoning_content with tools: in thinking mode with tools in the request, you must send back the reasoning_content from all earlier turns. If you drop it, the API returns a 400.
• Retired model id: deepseek-chat and deepseek-reasoner became inaccessible after July 24, 2026, 15:59 UTC, so requests that name them now fail.

Tip: The easiest fix for the tool-calling 400 is to append the full assistant message object (response.choices[0].message) to your history. It already carries content, reasoning_content and tool_calls.

Common causes of 422

• Out-of-range values: for example a negative max_tokens.
• Wrong types: a string where a number is expected.
• Bad thinking settings: thinking is set with {"thinking": {"type": "enabled"}} or "disabled". With the OpenAI SDK, pass it through extra_body.

Some settings are silently ignored rather than rejected. In thinking mode, temperature, presence_penalty and frequency_penalty have no effect, but they do not cause an error.

401 Authentication Fails

DeepSeek could not match your API key. It is almost always a copy-paste or environment variable problem.

1. Check the variable loaded. Print its length, never the key itself.
2. Check the base URL. Use https://api.deepseek.com for OpenAI-style calls, or https://api.deepseek.com/anthropic for Anthropic-style calls.
3. Remove stray spaces or quotes around the key in your .env file.
4. Create a new key on the DeepSeek platform API keys page if it still fails, then delete the old one.

402 Insufficient Balance

This is a billing error, not a bug. DeepSeek is prepaid, so when your balance reaches zero every call returns 402 until you add funds.

How to check your balance from code

DeepSeek has a balance endpoint: GET /user/balance. It returns is_available plus a list with total_balance, granted_balance and topped_up_balance, in CNY or USD.

import os, requests

r = requests.get(
    "https://api.deepseek.com/user/balance",
    headers={"Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}"},
    timeout=30,
)
data = r.json()
print("Can call API:", data["is_available"])
for b in data["balance_infos"]:
    print(b["currency"], "total:", b["total_balance"], "granted:", b["granted_balance"])

How to fix it

• Top up: add funds on the platform top-up page. Calls work again once the balance is positive.
• Watch granted credit: granted_balance only counts credit that has not expired yet.
• Alert early: run the balance check on a schedule and warn yourself before it hits zero.
• Cut cost: since August 16, 2026, off-peak rates are 50% lower than peak. Batch jobs can run off-peak.

Warning: Do not retry a 402 in a loop. It cannot succeed until you add funds, and a tight loop just floods your logs.

Current per-token prices are in my DeepSeek API pricing guide.

429 Rate Limit Reached

DeepSeek does not use the usual requests-per-minute tiers. Its main limit is concurrency: how many requests you have in flight at the same moment.

A request counts from the moment you send it until the response finishes. The limit is per account, so extra API keys do not add capacity.

The user_id twist

You can tag requests with a user_id for safety handling and cache isolation. On regular accounts, all user_ids share the account limit.

On accounts with expanded quotas, each user_id also gets its own cap of 2,500 (Flash) or 500 (V4-Pro). An empty id counts as one special user_id, so it can hit 429 on its own.

How to fix a 429

1. Cap your parallel workers below the limit, for example with a semaphore.
2. Retry with backoff: wait 1s, 2s, 4s, 8s, plus random jitter.
3. Use Flash for bulk work. It allows five times the concurrency of V4-Pro.
4. Ask for more: DeepSeek accepts capacity expansion requests and says they cost nothing extra.

For how this compares with Claude, OpenAI and Gemini tiers, see LLM API rate limits and tiers compared.

500 Server Error and 503 Server Overloaded

Both are on DeepSeek’s side. A 500 means an internal fault. A 503 means the servers are overloaded from high traffic.

• Retry after a short wait. DeepSeek’s own advice for both codes.
• Check the API status page linked from the DeepSeek docs before you debug your code.
• Contact DeepSeek at api-service@deepseek.com if 500 errors keep coming back for the same request.
• Add a fallback: switch from deepseek-v4-pro to deepseek-flash, or to another provider, after a few failures.

Timeouts, Empty Lines and “Server Busy”

Under heavy load, DeepSeek does not reject you right away. It holds the connection open and keeps it alive while your request waits in line.

What you will see

• Non-streaming calls: the server sends empty lines while you wait.
• Streaming calls: the server sends SSE comments that read : keep-alive.
• Hard limit: if inference has not started after 10 minutes, the server closes the connection.

The official OpenAI SDK handles the empty lines for you. If you parse raw HTTP yourself, skip blank lines and lines that start with a colon, or your JSON parser will crash.

Set a sensible client timeout

A short timeout, such as 30 seconds, will cut off requests that DeepSeek would have answered. Thinking mode at max effort can also run long on hard prompts.

Note: The “server is busy” message people see is mostly in the DeepSeek chat app and website. The API equivalent is a 503 or a long keep-alive wait.

Python Retry Code

DeepSeek’s API is OpenAI-compatible, so you use the official openai Python package with a different base URL. The SDK already retries some errors twice by default. The version below gives you full control.

import os, random, time
from openai import OpenAI, APIStatusError, APITimeoutError, APIConnectionError

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
    timeout=660,      # a bit over DeepSeek's 10-minute queue limit
    max_retries=0,    # we handle retries ourselves
)

RETRYABLE = {429, 500, 503}
MODELS = ["deepseek-v4-pro", "deepseek-flash"]

def ask(prompt, max_tries=5):
    for model in MODELS:
        for attempt in range(max_tries):
            try:
                r = client.chat.completions.create(
                    model=model,
                    messages=[{"role": "user", "content": prompt}],
                )
                return r.choices[0].message.content
            except APIStatusError as e:
                if e.status_code == 402:
                    raise SystemExit("Out of balance: top up your DeepSeek account")
                if e.status_code not in RETRYABLE:
                    raise  # 400, 401, 422: fix the request
                wait = min(60, 2 ** attempt) + random.uniform(0, 1)
                print(f"{model}: {e.status_code}, retry in {wait:.1f}s")
                time.sleep(wait)
            except (APITimeoutError, APIConnectionError):
                wait = min(60, 2 ** attempt) + random.uniform(0, 1)
                print(f"{model}: timeout or network error, retry in {wait:.1f}s")
                time.sleep(wait)
        print(f"Giving up on {model}, trying the next one")
    raise RuntimeError("All DeepSeek models failed")

print(ask("Explain HTTP 402 in one sentence."))

To limit concurrency for big jobs, wrap ask() with a threading.Semaphore set below your account limit. New to the SDK setup? Start with my DeepSeek API Python tutorial.

Troubleshooting: Common Problems and Fixes

• Code that worked in spring now fails: you are probably still calling deepseek-chat or deepseek-reasoner. Switch to deepseek-flash or deepseek-v4-pro.
• Old deepseek-v4-flash name: still accepted for now, but routed to DeepSeek-V4.1-Flash-1017 and billed at the Flash price. Move to deepseek-flash.
• 400 only on the second tool call: you dropped reasoning_content from history. Append the whole assistant message.
• JSON decode error on a raw HTTP call: you hit keep-alive empty lines. Strip blank lines before parsing.
• Temperature has no effect: expected in thinking mode. Turn thinking off if you need it.
• 429 with low traffic: check for stuck or very long streaming requests. Each one holds a concurrency slot until it ends.
• 402 although you topped up: confirm the payment went to the same account that owns the key, then check is_available on the balance endpoint.
• Errors inside Claude Code, Cline or other tools: check the tool uses the right base URL and a current model id. My DeepSeek in VS Code guide covers the settings.

Frequently Asked Questions

What does DeepSeek error 402 Insufficient Balance mean?

Your prepaid account balance has run out. Add funds on the DeepSeek platform top-up page, and calls will work again.

What is the DeepSeek API rate limit?

DeepSeek limits concurrent requests per account: 2,500 for deepseek-flash and 500 for deepseek-v4-pro. Going over returns HTTP 429.

Why does my DeepSeek request hang for minutes?

Under high traffic your request waits in a queue while the server sends keep-alive lines. If inference has not started after 10 minutes, the connection is closed.

Is deepseek-chat still working?

No. deepseek-chat and deepseek-reasoner were retired on July 24, 2026. Use deepseek-flash or deepseek-v4-pro instead.

Should I retry a DeepSeek 422 error?

No. A 422 means a parameter is invalid, so the same request will fail again. Read the error message, fix the field, then send it once more.

How do I fix DeepSeek 503 Server Overloaded?

Wait a moment and retry with exponential backoff. If it keeps happening, check the API status page or fall back to another model.

Do more API keys give me a higher DeepSeek limit?

No. The concurrency limit is per account, whatever key you use. Ask DeepSeek for a capacity expansion instead.

Sources

• DeepSeek API Docs: Error codes
• DeepSeek API Docs: Rate limit and isolation
• DeepSeek API Docs: Change log
• DeepSeek API Docs: Thinking mode
• DeepSeek API Docs: Get user balance
• DeepSeek: V4 preview release (deepseek-chat retirement notice)
• DeepSeek: V4-Pro GA release (peak and off-peak pricing)