DeepSeek API error codes: what each one means, and what to do first

Last updated · Written by Nova

Nov 4, 2026 · #deepseek#api#troubleshooting

Most API errors are not code errors. They are state errors — something about the account, the key, or the model name — and they show up as a number that tells you which state is wrong. Read the number first, then look at the payload.

401 — unauthorised

The key is wrong, revoked, or not being sent. Three causes cover almost every case: a key copied with a trailing space or a missing character, a key that was rotated and you still have the old one in an environment variable, and a client that puts the key in the wrong header.

First action: print the first and last four characters of the key your code is actually sending, and compare them with the console. Do not re-type it from a note.

402 — insufficient balance

This is billing, not inference. The request never reached the model. Four situations produce it: the prepaid balance is genuinely exhausted, the balance is fine but the key belongs to a group with no allowance, a request is being billed to a key you did not expect, and a very long context request exceeds what the remaining balance can cover.

First action: check the balance and the per-request cost line in the console before touching the payload.

404 — model not found

The model name is not one your key can call. Names are exact strings; a typo becomes a 404 rather than a silent fallback. The second cause is a group that only exposes one family: a key created for a DeepSeek-only group cannot call a model that belongs to another group.

First action: list the models available to that key, then compare character by character with what your client sends.

429 — rate limited

You are sending faster than the allowance, or the upstream is briefly saturated. 429 is usually transient, which makes it dangerous: retrying without backoff turns a short blip into a longer outage.

First action: confirm your client backs off exponentially and caps retries. Then check whether a single job is fanning out many parallel requests.

400 — bad request

The payload is malformed for the model you chose: an unsupported parameter, a message role the model does not accept, an image sent to a text-only model, or a tool schema that does not parse. The error body usually names the field.

First action: reduce the request to one message with no tools, then add features back until it breaks again.

500 / 502 / 503 — server side

Something upstream failed. If it happens once, retry. If it repeats on the same prompt, it is usually the payload triggering it, not the network.

First action: retry once, then capture the request id and the exact prompt if it repeats.

The order to check things in

  1. Status code — it names the layer (auth / billing / model / rate / payload / upstream).
  2. The error body — most gateways name the offending field or the reason.
  3. The key — which group it belongs to, whether it is still valid.
  4. The model name — exact string, allowed for that key.
  5. Only then the application code.

Endpoint reference and the exact error bodies are in the docs.

Questions people actually ask

What does a 402 mean on a DeepSeek API?

Insufficient balance. The request was rejected before inference: the prepaid balance is exhausted or the key's group has no allowance left.

Why do I get 404 for a model that exists?

The model name is not one your key can call. Names are exact strings, and a key tied to one group cannot call models from another.

Should I retry a 429 immediately?

No. Back off exponentially and cap the retries; immediate retries turn a short rate limit into a longer outage.

Is a 400 always my code's fault?

Usually yes: an unsupported parameter, a role the model rejects, or a malformed tool schema. The error body normally names the field.

How do I tell a transient 500 from a payload problem?

Retry once. If the same prompt fails again with the same id, it is the payload; if it succeeds, it was upstream.

Reference: DeepSeek API documentation. Error semantics and build history are from the official source.