Error codes & troubleshooting
Find the likely cause of a failed request and choose the next step.
On this page
Start with the responseStatus referenceAuthentication and endpoint errorsRate limit or exhausted quota?An answer stopped halfwayPrepare a useful support reportStart with the response#
Record the HTTP status, error type, message, time and request ID if present. Remove authorization headers and sensitive prompt content before sharing diagnostics. Provider-specific messages are more informative than the status alone.
Status reference#
These are common API conventions and DeepSeek reference errors. An independent provider can return different error bodies or use additional codes.
| Status | Check first | Next step |
|---|---|---|
| 400 | JSON body and field types | Correct the body using the error message |
| 401 | Key, authentication header and provider | Use an active key from the same provider as the endpoint |
| 402 | Balance or billing access | Check billing with the provider that issued the key |
| 404 | Base URL, version prefix and model ID | Remove duplicated paths and verify the requested resource |
| 422 | Unsupported parameters or values | Start with a minimal request and add options individually |
| 429 | Rate, concurrency or quota details | Reduce parallel work or wait for the stated quota reset |
| 500 / 503 | Provider or upstream availability | Retry after a short delay; stop after a bounded number of attempts |
Authentication and endpoint errors#
Make sure environment variables are set in the terminal running the client. Avoid trailing spaces in copied keys. A key from the official DeepSeek platform will not automatically authenticate with an independent service.
Use the provider's documented base URL. SDKs append their own endpoint path: a base ending in /chat/completions can produce a duplicated path. Claude Code needs a Messages-compatible endpoint; Codex needs Responses support.
Rate limit or exhausted quota?#
HTTP 429 alone does not identify the cause. Inspect the error type and reset information. A request-per-second or concurrency limit calls for pacing; an exhausted plan window calls for waiting until that window resets or following the provider's plan options.
Honor Retry-After when present. Use bounded exponential backoff with jitter for transient failures, and do not retry authentication or invalid-parameter errors unchanged. Retrying after a timeout may create another chargeable request.
An answer stopped halfway#
Check whether the stream closed normally, hit an output limit or lost the connection. Preserve the partial answer as incomplete. Do not silently merge a fresh generation into it. See streaming responses.
Prepare a useful support report#
Include the client and version, API format, model ID, sanitized error, timestamp with timezone, and a minimal reproduction without a key. Never send a full environment dump.
References: DeepSeek error codes and rate limits.
Guide updated November 5, 2026 · All tutorials