DeepSeek API server unavailable: diagnose, retry, fall back

A server unavailable error from a DeepSeek endpoint is almost always upstream capacity — rate limits, overloaded nodes or a timed-out request — not a problem with your API key. This page walks through confirming the cause, building a bounded retry policy, and falling back to a second model on the same key.

What server unavailable actually means

DeepSeek lanes surface capacity pressure as HTTP 5xx responses — 500/502/503, timeout-style failures, or 429 when the limit is rate rather than capacity. None of these mean your credentials are wrong: auth failures come back 401 with a clear message. The response usually carries a request id; keep it, it is what support needs if an error persists.

On a relay like KeyoAPI the same status codes mean the same thing: the upstream DeepSeek capacity was unavailable for that attempt. Your client decides whether to retry, and how hard.

Confirm it is the upstream, not your code

Three checks separate capacity errors from client bugs: the same key works on a cheaper model, the error reproduces across several minutes rather than only once, and the failing requests are spread across different prompts rather than one oversized payload. If all three point to capacity, retries and fallback are the right response.

The one-token smoke test against the flash lane is the fastest first check — if this answers while the heavier lane fails, capacity is the issue and a fallback model is the right move.

curl https://www.keyoapi.xyz/v1/chat/completions \
  -H "Authorization: Bearer $KEYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4.1-flash","messages":[{"role":"user","content":"ping"}],"max_tokens":1}'

Build a bounded retry policy

Retry only what is retryable — 408, 429 and 5xx status codes and network timeouts — and cap attempts at three or four. Space them with exponential backoff plus jitter: sleep for min(0.5 × 2^attempt, 8) seconds scaled by a random 0.5–1.5 factor, so concurrent workers do not re-stampede the same upstream. A shared retry budget across your workers keeps retry amplification bounded when an upstream degrades.

Fall back to a second model on the same key

Retries only help when capacity comes back. For hard deadlines, switch model= instead: deepseek-v4.1-flash for cheap classification, deepseek-v4-pro-0813 when you need the heavier lane, or glm-5.3 / kimi-k3 as cross-vendor chat alternatives. The base URL and API key do not change — fallback is a one-field switch in the request body.

Treat fallback as a deliberate route, not a silent rewrite: log which model served each response, because pricing and output shape differ per lane. Live rates for every fallback candidate are on the full pricing list and the deepseek lane is covered in detail on the DeepSeek API pricing page.

Run DeepSeek inside agent harnesses without melting capacity

Agent and eval harnesses multiply capacity problems: dozens of workers each firing multi-step chains turn one slow upstream into a self-inflicted outage. Bound the harness the same way you bound retries — a hard concurrency cap on in-flight DeepSeek calls, a per-stage timeout (planner, tool, critic) rather than one global timeout, and a single shared retry budget so a degraded lane throttles the whole harness instead of queueing forever.

Make harness steps idempotent where you can, checkpoint intermediate state between steps, and put the cheapest model on the highest-frequency step. A harness that burns deepseek-v4.1-flash on routing and reserves deepseek-v4-pro for the hard steps survives upstream wobble far better than one that sends every step to the heaviest lane.

Watch cost amplification while you retry

Every retry of a timed-out request risks paying twice if the first attempt eventually completes upstream. For expensive calls, prefer idempotency keys or at-least-once accounting in your own logs, and stop retrying non-idempotent tool-triggering requests automatically — surface those to the orchestrator instead.

Retry storms also inflate spend indirectly: a 4-request retry policy against a 5-second timeout can triple your effective request count exactly when the upstream is slowest. The concurrency cap from the harness section is the guardrail that keeps this bounded.

A practical response checklist

FAQ

Related guides