<!-- Generated from public website sources; do not edit this file. -->

> DSSUB design reference. Account, payments and API are not connected; prices, policies and setup examples require independent launch verification.

# Error codes & troubleshooting
Diagnose dssub API failures, connection timeouts and coding-client setup problems. Start with one small request, then follow the steps for the returned error.

## Current availability
DSSUB is a design preview. Account, payment and API services are not connected. The examples and expected behavior below are integration references, not a verified production contract. A `.invalid` endpoint cannot accept real requests.


## Start here
1. Record the client version, selected model, request path, HTTP status, error message and time with timezone. Record a request ID if returned; it is not guaranteed.
2. Check [Your plan](/account/plan), [Usage](/account/usage) and the key's billing mode in [API keys](/account/keys). Website login and an inference API key are different credentials.
3. Try the minimal request below using the same key and network as the failing client. Chat Completions success does not by itself verify Messages, Responses or advanced client tools.
4. Read status and message together. Error wrappers vary: useful text may appear in `error.message`, `error.code`, `detail`, or a plain HTML proxy response.

Remove keys, authorization headers, cookies, private code and prompt content before sharing diagnostics. Do not send an environment dump or enable verbose HTTP tracing with a real key.

## Use the correct connection details
| Client | Base URL setting | Final request path |
| --- | --- | --- |
| OpenAI SDK / Chat Completions | `https://api.dssub.invalid/v1` | `/v1/chat/completions` |
| OpenCode with `@ai-sdk/openai-compatible` | `https://api.dssub.invalid/v1` | `/v1/chat/completions` |
| Claude Code CLI, `ANTHROPIC_BASE_URL` | `https://api.dssub.invalid` | `/v1/messages` |
| Codex, Responses provider `base_url` | `https://api.dssub.invalid/v1` | `/v1/responses` |

For SDKs, do not put the final endpoint in the base URL. Claude Code adds `/v1/messages`; use the origin without `/v1`. The website host `dssub.com` is not the inference API host. The public proxy exposes the paths above and `/v1/models`; do not rely on unversioned paths or `/v1/responses/compact`.

Use `deepseek-flash`, `deepseek-v4-pro`, or its dssub alias `deepseek-pro`. A plan named Pro does not select the Pro model automatically. Older keys may allow only Flash; see [models and compatibility](/docs/models/index.md).

## Make one diagnostic request
Set `DSSUB_API_KEY` securely in the terminal running the command, as described in [API keys](/docs/api-keys/index.md). These shell examples use macOS / Linux syntax. Windows users can use the Python example with the PowerShell environment setup in [API quickstart](/docs/quickstart/index.md).

First, check DNS, TLS and HTTP reachability without a key or generation:

```sh
curl --silent --show-error --connect-timeout 10 --max-time 20 \
  --output /dev/null --write-out 'HTTP %{http_code}\n' \
  https://api.dssub.invalid/v1/models
```

An authentication rejection, normally 401, proves an HTTP response arrived; it does not prove your key, model or upstream is working. HTTP `000` is cURL's lack-of-response indicator, not a server status. A 502/503/504 means an HTTP component responded but the service path needs investigation.

Next, send one short text request. It can consume allowance or API credit. This command does not automatically retry. The 90-second limit is a diagnostic budget, not a latency guarantee.

```sh
curl --silent --show-error --connect-timeout 10 --max-time 90 \
  --write-out '\nHTTP %{http_code}; total %{time_total}s\n' \
  https://api.dssub.invalid/v1/chat/completions \
  -H "Authorization: Bearer ${DSSUB_API_KEY:?Set DSSUB_API_KEY first}" \
  -H 'Content-Type: application/json' \
  --data '{"model":"deepseek-flash","messages":[{"role":"user","content":"Say hello briefly."}],"max_tokens":128,"stream":false}'
```

The command prints error bodies. HTTP errors do not necessarily produce a nonzero cURL exit code; read the printed status. With reasoning enabled, a small output budget can be consumed before final answer text appears. Inspect `finish_reason` and usage before treating empty text as a connection error.

For Python, install `openai` and `httpx`, then set explicit timeouts and disable SDK retries during diagnosis:

```python
import os
import httpx
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DSSUB_API_KEY"],
    base_url="https://api.dssub.invalid/v1",
    timeout=httpx.Timeout(90.0, connect=10.0),
    max_retries=0,
)
response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Say hello briefly."}],
    max_tokens=128,
    stream=False,
)
print(response.choices[0].message.content)
```

The Python read timeout limits waiting for network data; it is not necessarily a total wall-clock deadline for a stream.

## Status and message reference
These messages come from the current dssub gateway and billing implementation. Clients, edge proxies and upstream providers can wrap them differently or return additional errors. HTTP 502/504 and 422 below describe possible intermediary/provider responses, not dedicated dssub billing codes.

| Status | Message or symptom | First action |
| --- | --- | --- |
| 400 | `Unsupported request field`, `Unsupported model` | Remove unsupported fields; use a dssub model ID |
| 400 | `Stored Responses are not enabled` | Omit `store` or send `store: false`; send history explicitly |
| 400 | `Hosted tools require a separate tariff`, `Custom tool format is not enabled` | Remove the unsupported hosted/custom tool; use supported client function tools |
| 400 | `Only metered text input is enabled`, `Tools must be an array`, `Only a single completion is supported` | Use text, an array of supported tools, and `n: 1` or omit `n` |
| 400 | `MULTI_INVALID_OUTPUT_LIMIT`, `MULTI_UNSUPPORTED_OVERRIDE` | Use a positive integer output limit; remove routing overrides and unsupported `extra_body` options |
| 401 | `API key required`, `ACCESS_DENIED` | Check the credential sent, expiry and revocation |
| 403 | `MODEL_DENIED`, `ACCESS_DENIED` | Check key model permissions and account access |
| 402 | `INSUFFICIENT_BALANCE` | Check API credit, held funds and key billing mode |
| 404 | Endpoint/model not found | Check host, `/v1`, final path and model |
| 409 | Request/admission conflict | Stop duplicate attempts; report a persistent conflict |
| 413 | Request too large, `MULTI_REQUEST_TOO_LARGE` | Reduce history, pasted files and tool schemas |
| 422 | Parameter validation failure | Correct the named field starting from a minimal request |
| 429 | `PLAN_EXHAUSTED` | Check active plan, applicable windows, held allowance and billing mode |
| 429 | `CONCURRENCY_LIMIT`, `RATE_LIMIT` | Reduce parallel tasks or request frequency |
| 500 | Internal/provider error | Preserve diagnostics; use bounded retries for transient failures |
| 502 | Bad Gateway | Isolate client/network versus gateway/upstream |
| 503 | `MODEL_UNAVAILABLE`, `SIAPI_BILLING_UNAVAILABLE`, `SIAPI_BILLING_NOT_CONFIGURED`, or proxy error | Check service status; persistent billing/configuration failures need support |
| 504 | Gateway Timeout | Reduce workload; distinguish gateway and client timeouts |
| No HTTP status | Timeout, DNS, TLS, connection reset | Follow the network steps below |

## Fix authentication and model access
1. Use a key created in dssub [API keys](/account/keys), not a Clerk login token or an official DeepSeek/OpenAI/Anthropic key.
2. For the diagnostic request, send `Authorization: Bearer <key>`. Check extra spaces, literal placeholders and missing environment variables in the actual client process.
3. Replace an expired/revoked key and update the client. Restart desktop/IDE applications after changing their credential source; a shell export does not update an already-running application.
4. For `MODEL_DENIED` or another model permission error, inspect allowed models and test Flash. If an older key lacks Pro access, create a new key with the required models. Do not rotate a valid key merely because of a 502 or timeout.
5. If access remains denied, send support the sanitized error and time, never the complete key.

## Fix quota, balance and concurrency errors
1. Read the message: `PLAN_EXHAUSTED`, `RATE_LIMIT` and `CONCURRENCY_LIMIT` need different actions.
2. For `PLAN_EXHAUSTED`, check whether an eligible plan is active and whether the request fits both applicable windows after used and reserved tokens. Check reset times in [Your plan](/account/plan); the error does not guarantee reset fields or a `Retry-After` header.
3. Shorten input and lower the output budget if the reservation cannot fit. Pro uses 3.5 times Flash-equivalent allowance. Pending/uncertain requests can retain reservations; a local timeout is not proof of release.
4. Inspect the key's billing mode. Plan only never falls back to credit. API credit only does not use a plan. Auto can fall back when automatic credit usage is enabled; insufficient credit can then produce `INSUFFICIENT_BALANCE`. Enabling fallback permits credit spending, so choose it deliberately.
5. For `CONCURRENCY_LIMIT`, stop parallel agents and wait for in-flight work to settle. For `RATE_LIMIT`, pause the request loop and reduce frequency. Persistent unresolved reservations need support.
6. Honor `Retry-After` when present. Otherwise use bounded backoff for transient rate limits. Waiting a few seconds does not resolve an exhausted 5-hour or 7-day window.

## Fix unsupported requests and large context
1. Start with the text-only diagnostic request. Add streaming, history, tools and reasoning options one at a time.
2. Remove `store: true`, `previous_response_id`, `background`, `metadata` and provider routing overrides from direct requests. These are outside the current public contract. Send conversation history rather than relying on stored Responses.
3. Remove provider-hosted tools such as `type: web_search` and Responses tools with `type: custom`. Client-executed JSON-schema function tools are different: a client function named `web_search` is not rejected merely because of its name.
4. For media rejection, use text. Current public validation rejects media input; upstream model capabilities do not override this restriction.
5. For 413 or a context-length error, start a fresh conversation with a concise summary, remove large files and unused tool schemas, and lower the output budget. HTTP body size and model context length are separate limits.
6. For encrypted-only or redacted thinking replay errors, start a fresh conversation. The bridge needs plaintext reasoning for supported replay; do not reuse provider-specific encrypted reasoning from another service.

## Resolve 502 Bad Gateway
1. Save the status, time and sanitized body. HTML errors can come from a proxy before any JSON API response; this is not automatically a key problem.
2. Check [Service status](/service-status/index.md) and incident notices. That page alone is not a per-request health check; run the no-key probe above.
3. If the probe also returns 502, pause generation and report the host/time. Gateway process failure, upstream connection failure or an intermediary can be involved; service logs are needed to establish the cause.
4. If reachability works, try one short request with parallel jobs stopped. If only one client fails, compare URL and proxy settings. Where your network permits it, compare an alternative network to isolate a local proxy/VPN issue.
5. Retry at most twice after delays such as 2 and 5 seconds with random jitter, then stop and contact support. Check Usage before resubmitting if the original may have reached the model; a new request can incur another charge.

## Resolve 504 Gateway Timeout
1. Confirm an actual HTTP 504 response. `APITimeoutError`, `ReadTimeout`, `ETIMEDOUT` or cURL exit 28 without an HTTP response are client/network timeouts instead.
2. Note elapsed time and whether stream data arrived. Consistently timed failures suggest a deadline but do not identify which component imposed it.
3. Try a fresh, short text prompt with a smaller output limit and no parallel agents. Reintroduce context and optional features gradually if it succeeds.
4. Try streaming for long answers if supported. It improves progress visibility but does not remove upstream compute or proxy idle timeouts.
5. If the client gives up first, adjust its documented read/idle timeout within a finite budget. Increasing a client timeout cannot repair an HTTP 504 generated by a gateway.
6. Check Usage and pending allowance, then follow the bounded retry policy below. Persistent 504s on small requests need support with timing details.

## Resolve connection timeouts, DNS and TLS errors
| Symptom | Interpretation | Next step |
| --- | --- | --- |
| cURL exit 6 / host resolution failure | DNS lookup failed | Confirm `api.dssub.com`; check resolver/network |
| cURL exit 7 / connection refused | TCP connection failed | Check firewall, proxy, VPN and port 443 |
| cURL exit 28 / `ConnectTimeout` / `ETIMEDOUT` | A deadline expired | Distinguish connection establishment from waiting for data |
| `ReadTimeout` / `APITimeoutError` | Client stopped waiting | Compare a short request; inspect read timeout and retries |
| cURL exit 35 or 60 / TLS certificate error | Handshake or certificate validation failed | Check system time, trust store and any required organizational CA |
| Connection reset / stream disconnected | Peer or intermediary closed the connection | Preserve partial output and compare the network path |

1. Run the no-key probe in the same environment as the client: terminal, container, remote host or IDE. A working browser elsewhere does not verify that environment.
2. Review `HTTP_PROXY`, `HTTPS_PROXY` and `ALL_PROXY` locally for stale routing. Do not publish proxy URLs containing credentials. Follow required network settings rather than bypassing them blindly.
3. Correct DNS, firewall and certificate issues first. Do not disable TLS verification or use `curl -k` as a fix.
4. If only large requests time out, reduce context/output and inspect connect, read and stream-idle settings separately.
5. Stop retry loops and check Usage. Timeout/disconnect does not prove upstream processing stopped, no tokens were used, or a reservation was released.

## Claude Code CLI checklist
1. Record `claude --version`. Set `ANTHROPIC_BASE_URL` to `https://api.dssub.invalid` and use your dssub key as `ANTHROPIC_AUTH_TOKEN`. Review conflicting saved credentials/settings locally.
2. Set `ANTHROPIC_MODEL` and the default Opus/Sonnet/Haiku and subagent model variables from the [Claude Code guide](/docs/claude-code/index.md) to the intended model. Background model selection can fail even when the main chat works.
3. Restart the CLI in that terminal and test a new short conversation. A direct Messages check uses `/v1/messages`, a `messages` array, a positive `max_tokens` and `anthropic-version: 2023-06-01`.
4. For 404, check duplicated `/v1` or an unsupported auxiliary endpoint. For 400, inspect tools, media and thinking payloads using the steps above.
5. If Chat Completions works but Messages fails, report the Messages error separately. Protocol conversion does not establish support for every client feature. These shell instructions apply to the CLI; desktop/managed integrations can use different settings.

## Codex checklist
1. Record `codex --version`. Back up the existing config and model catalog. Merge changes; duplicate TOML tables can prevent startup before any HTTP request.
2. In `~/.codex/config.toml`, match `model_provider` to the provider table, set its `base_url` to `https://api.dssub.invalid/v1` and `wire_api` to `responses`. Use a dssub model ID and an `env_key` naming the environment variable containing your key.
3. Restart in that environment and test a fresh session. A direct `/v1/responses` check uses `input`, `max_output_tokens` and `store: false`. Chat Completions success alone is not a Codex test.
4. For hosted search, custom tools, stored Responses or unsupported fields, follow the matching steps above. If the client cannot emit supported requests, retain the version/error for support; repeatedly changing keys will not solve it.
5. For 404 during compaction, record the path. `/v1/responses/compact` is not exposed by the current public proxy. Start a fresh session with a concise summary; check installed-client provider/model capabilities before enabling remote compaction.
6. For stalled streams, inspect `stream_idle_timeout_ms`, `request_max_retries` and `stream_max_retries` in the provider settings. Disable automatic retries during diagnosis where supported. Preserve existing model metadata instead of copying another provider's context size.

## OpenCode checklist
1. Record `opencode --version`. In `/connect`, choose `Other` and use the same provider ID as in `opencode.json`, for example `dssub`.
2. Use `npm: "@ai-sdk/openai-compatible"`, `options.baseURL: "https://api.dssub.invalid/v1"` and an exact dssub model ID as the key under `models`. A display name is not an API model ID.
3. Merge valid JSON, restart if needed and select the model with `/models`. If the provider is missing, check syntax/location before changing credentials.
4. For authentication errors, reconnect the key under the matching provider ID. For endpoint errors, include `/v1` once and do not append `/chat/completions` to `baseURL`.
5. Test a new short conversation, then tools and longer context. Follow request/network steps for 400 or stream interruptions; record the selected provider/model for support.

## An answer stopped halfway
1. Check the protocol's completion signal and any error event. HTTP 200 at stream start does not guarantee a completed generation.
2. Distinguish an output limit (`finish_reason: length` or incomplete Responses result) from a disconnected stream. A budget limit needs a deliberate continuation or larger supported budget; a disconnect needs network/timeout investigation.
3. Mark partial output incomplete. Do not silently append a new generation or re-execute partially completed tool actions. Check whether a tool already changed files or performed an external action before repeating it.
4. Check [Usage](/account/usage). Missing final usage can leave a pending/uncertain reservation for reconciliation. Missing usage or a closed connection does not imply a zero charge.
5. Retain the last event type, elapsed time and sanitized error. See [streaming responses](/docs/streaming/index.md).

## Retry without creating a loop
Fix invalid requests and authentication/access failures before retrying. For a temporary 429 rate limit or 500/502/503/504, honor `Retry-After` if present; otherwise try at most two retries with increasing delays and jitter, then stop. Quota exhaustion needs its window/billing issue resolved first. Persistent model/billing configuration failures need support.

Disable overlapping retries in the SDK, client and your own script while diagnosing. Timed-out requests may already have run; check Usage and decide whether to resubmit. Repeating generation is a new potentially billable request, not a guaranteed resume or free retry.

## Prepare a useful support report
Use [Help & contact](/support/index.md) and include the following with secrets and private content removed:

```text
Time and timezone:
Client / version / operating system:
API host and final path (no query secrets):
Model ID / streaming on or off:
HTTP status, or network exception / cURL exit code:
Sanitized error code and message:
Elapsed time / whether response data arrived:
Request ID (only if returned):
Key billing mode / plan reset / pending usage:
Does the no-key probe work? Does one short text request work?
Minimal request with key and private prompt removed:
```

Connection settings were checked against the project implementation on November 6, 2026. Client settings can change by version. References: [Claude Code gateway configuration](https://code.claude.com/docs/en/llm-gateway-connect), [Codex configuration reference](https://developers.openai.com/codex/config-reference/), [OpenCode custom providers](https://opencode.ai/docs/providers/), and [cURL exit codes](https://curl.se/libcurl/c/libcurl-errors.html).

---

HTML source: [Error codes & troubleshooting — dssub Tutorials](/docs/error-codes/)
