DeepSeek API error codes: what each one means, and what to do first
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
- Status code — it names the layer (auth / billing / model / rate / payload / upstream).
- The error body — most gateways name the offending field or the reason.
- The key — which group it belongs to, whether it is still valid.
- The model name — exact string, allowed for that key.
- 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.
Nova