API GUIDES

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.

On this pageCurrent availabilityStart hereUse the correct connection detailsMake one diagnostic requestStatus and message referenceFix authentication and model accessFix quota, balance and concurrency errorsFix unsupported requests and large contextResolve 502 Bad GatewayResolve 504 Gateway TimeoutResolve connection timeouts, DNS and TLS errorsClaude Code CLI checklistCodex checklistOpenCode checklistAn answer stopped halfwayRetry without creating a loopPrepare a useful support report
Preview connection · Configuration examples only. Check service availability before using a real key. Example only: https://api.dssub.invalid/v1 is not a live endpoint.

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, Usage and the key's billing mode in API 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#

ClientBase URL settingFinal request path
OpenAI SDK / Chat Completionshttps://api.dssub.invalid/v1/v1/chat/completions
OpenCode with @ai-sdk/openai-compatiblehttps://api.dssub.invalid/v1/v1/chat/completions
Claude Code CLI, ANTHROPIC_BASE_URLhttps://api.dssub.invalid/v1/messages
Codex, Responses provider base_urlhttps://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.

Make one diagnostic request#

Set DSSUB_API_KEY securely in the terminal running the command, as described in API keys. These shell examples use macOS / Linux syntax. Windows users can use the Python example with the PowerShell environment setup in API quickstart.

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.

StatusMessage or symptomFirst action
400Unsupported request field, Unsupported modelRemove unsupported fields; use a dssub model ID
400Stored Responses are not enabledOmit store or send store: false; send history explicitly
400Hosted tools require a separate tariff, Custom tool format is not enabledRemove the unsupported hosted/custom tool; use supported client function tools
400Only metered text input is enabled, Tools must be an array, Only a single completion is supportedUse text, an array of supported tools, and n: 1 or omit n
400MULTI_INVALID_OUTPUT_LIMIT, MULTI_UNSUPPORTED_OVERRIDEUse a positive integer output limit; remove routing overrides and unsupported extra_body options
401API key required, ACCESS_DENIEDCheck the credential sent, expiry and revocation
403MODEL_DENIED, ACCESS_DENIEDCheck key model permissions and account access
402INSUFFICIENT_BALANCECheck API credit, held funds and key billing mode
404Endpoint/model not foundCheck host, /v1, final path and model
409Request/admission conflictStop duplicate attempts; report a persistent conflict
413Request too large, MULTI_REQUEST_TOO_LARGEReduce history, pasted files and tool schemas
422Parameter validation failureCorrect the named field starting from a minimal request
429PLAN_EXHAUSTEDCheck active plan, applicable windows, held allowance and billing mode
429CONCURRENCY_LIMIT, RATE_LIMITReduce parallel tasks or request frequency
500Internal/provider errorPreserve diagnostics; use bounded retries for transient failures
502Bad GatewayIsolate client/network versus gateway/upstream
503MODEL_UNAVAILABLE, SIAPI_BILLING_UNAVAILABLE, SIAPI_BILLING_NOT_CONFIGURED, or proxy errorCheck service status; persistent billing/configuration failures need support
504Gateway TimeoutReduce workload; distinguish gateway and client timeouts
No HTTP statusTimeout, DNS, TLS, connection resetFollow the network steps below

Fix authentication and model access#

  1. Use a key created in dssub API 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; 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 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#

SymptomInterpretationNext step
cURL exit 6 / host resolution failureDNS lookup failedConfirm api.dssub.com; check resolver/network
cURL exit 7 / connection refusedTCP connection failedCheck firewall, proxy, VPN and port 443
cURL exit 28 / ConnectTimeout / ETIMEDOUTA deadline expiredDistinguish connection establishment from waiting for data
ReadTimeout / APITimeoutErrorClient stopped waitingCompare a short request; inspect read timeout and retries
cURL exit 35 or 60 / TLS certificate errorHandshake or certificate validation failedCheck system time, trust store and any required organizational CA
Connection reset / stream disconnectedPeer or intermediary closed the connectionPreserve 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 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. 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.

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 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, Codex configuration reference, OpenCode custom providers, and cURL exit codes.

Guide updated November 5, 2026 · All tutorials