ZH

Search

API Troubleshooting: 401, model not found, timeout, stream drop

Practical fixes when coding agents fail against an OpenAI-compatible gateway.

Admin3 min read
troubleshootingapisetup

API Troubleshooting: 401, model not found, timeout, stream drop

When Codex, Cline, OpenCode, or SDKs fail, start with these four checks. Mature gateway docs all boil down to the same order: auth → model id → host → stream/network.

0. Baseline checks (do these first)

Terminal window
export BASE=https://api.earbowe.com/v1
export KEY=sk-YOUR-KEY


# 1) models
curl -sS -o /tmp/models.json -w '%{http_code}\n' \
  -H "Authorization: Bearer $KEY" "$BASE/models"


# 2) simple chat
curl -sS -o /tmp/chat.json -w '%{http_code}\n' \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  "$BASE/chat/completions" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'

If curl fails, fix the gateway path before blaming the agent UI.

China direct: set BASE=https://api.3861343.xyz/v1.

1. 401 Unauthorized

Meaning: key rejected or missing.

Check Action
Key format Must be full sk-..., no spaces/newlines
Console status Key active, not deleted
Header Authorization: Bearer sk-...
Env var Tool actually reads the variable you set

Agent tips:

  • Cline: re-paste key in OpenAI Compatible settings
  • Codex: confirm OPENAI_API_KEY in the same shell that launches codex
  • OpenCode: confirm EARBOWE_API_KEY (or your configured env name) is exported

2. Model not found / invalid model

Meaning: the model string is not on this gateway.

Fix:

  1. GET /v1/models
  2. Copy an exact id
  3. Paste that id into the agent (no marketing aliases)

Common mistakes:

  • Using a brand name instead of API id
  • Assuming OpenAI/Anthropic public names always exist on every gateway
  • Stale local model dropdown cache

3. Timeout / connection reset / very slow

Meaning: network path or host choice.

Situation Try
In China / Asia, global host slow https://api.3861343.xyz/v1
Local proxy intercepts HTTPS Temporarily disable proxy for API host tests
DNS weirdness curl -v and check which IP you hit
Only agent fails, curl works Agent base URL missing /v1 or wrong field

Rule: curl works + agent fails almost always means agent config, not model quality.

4. Stream interrupted / incomplete replies

Meaning: streaming path unstable or client abort.

Debug order:

  1. Non-stream request (curl above) — if OK, model path works
  2. Re-enable stream in one client only
  3. Check VPN/proxy idle timeouts
  4. Reduce concurrent agent sessions

Earbowe supports streaming when clients request it; flaky local networks still break long streams.

5. Base URL mistakes (very common)

Correct:

https://api.earbowe.com/v1

Wrong:

https://api.earbowe.com
https://api.earbowe.com/v1/chat/completions   # too long for baseURL fields
https://www.earbowe.com/v1                    # content site, not API
https://earbowe-astro-preview.pages.dev/v1    # Pages content, not gateway

OpenAI-compatible clients append /chat/completions themselves.

6. Quick matrix

Tool Key fields
curl / SDK base_url + api_key + model id
Codex CLI OPENAI_BASE_URL, OPENAI_API_KEY
Cline OpenAI Compatible → Base URL + key + model
OpenCode provider.*.options.baseURL + apiKey + models map

Related posts