Fix API connection errors before an HTTP response
Start with the failure stage: URL parsing → name resolution → connection and TLS → HTTP response → model result. Invalid URL, ENOTFOUND and certificate errors need different checks from a returned 401 or 429. Use the affected device and network, compare the client with a small read-only probe, and keep the exact error before changing configuration.
Which layer failed?
A missing request row is a clue, not proof of a particular cause. The client might fail before reaching the gateway, while rejected requests, log filters or recording delays can also explain a missing row. Start with what the client actually received.
| Signal | What it tells you | Next check |
|---|---|---|
| Invalid URL / ERR_INVALID_URL | The client could not construct a usable URL. | Check the raw API Host or Base URL field and how this client appends paths. |
| ENOTFOUND / EAI_AGAIN | Name lookup failed; EAI_AGAIN indicates a temporary lookup failure. | Check the exact hostname, resolver result and the app's network environment. |
| Connection refused / reset / timeout | A connection was refused, closed or timed out. The stage matters. | Compare app and curl behavior; check proxy, firewall and whether any HTTP response arrived. |
| Certificate verification / hostname error | TLS peer verification did not succeed. | Check device time, hostname, certificate trust and any managed HTTPS inspection. |
| HTTP 401 / 403 / 429 / 5xx | An HTTP responder returned a status. | Identify the responding service from the headers and body, then follow the API error guide. |
Fix Invalid URL without guessing the path
Copy only the URL into the API Host or Base URL field. Check for a pasted Markdown link, surrounding quotes or brackets, a duplicated https:// prefix, and unexpected whitespace. An empty or invalid base can make the JavaScript URL constructor throw before any network request. A syntactically valid URL can still point at the wrong API route.
| Configuration shown in our guide | Value to enter |
|---|---|
| OpenAI SDK base_url / baseURL; Codex base_url | https://api.router.one/v1 |
| Claude Code ANTHROPIC_BASE_URL | https://api.router.one |
| NextChat BASE_URL | https://api.router.one |
| Immersive Translate custom endpoint; Copilot models[].url for Chat Completions | https://api.router.one/v1/chat/completions |
- These values apply to the configurations in the linked integration guides. Other providers, client versions or API types can use different fields.
- Keep the API key in its dedicated secret field. A key does not belong in the URL.
- After correcting the field, restart or reload the client if it reads configuration only at startup. Confirm the actual request path before changing /v1 again.
Check DNS on the affected device
Run these read-only lookups on the same device and network where the app fails. Record the resolver and returned addresses, or the exact lookup error. router.one and api.router.one are different hostnames: the website opening does not establish that the API hostname resolves.
nslookup api.router.one nslookup router.one
- Compare with a second network or an approved alternative resolver. Different answers alone do not prove interference: caches and routing can legitimately differ.
- A successful nslookup does not prove the app uses the same resolution path. Check local hosts overrides, the app's proxy settings, VPN/TUN state, and its runtime resolver. Node.js dns.lookup uses the operating system's lookup facility.
- ENOTFOUND alone does not establish that the domain expired or the provider is down. EAI_AGAIN suggests a temporary lookup failure; retry briefly, then investigate recurring failures.
Probe HTTPS without sending an API key
This macOS/Linux command makes a read-only GET to the model-list path. It sends no API key and requests no generation. -q skips curl's default config file; certificate verification stays enabled and redirects are not followed. The response body is discarded: first inspect the status, Content-Type and Location headers. Remove --output /dev/null to inspect the body if the response source remains unclear. On Windows PowerShell, use curl.exe, put the command on one line and replace /dev/null with NUL.
curl -q --silent --show-error --connect-timeout 10 --max-time 20 \
--dump-header - --output /dev/null \
--write-out 'http_code=%{http_code} remote_ip=%{remote_ip}\n' \
https://api.router.one/v1/models| Result | Interpretation |
|---|---|
| curl: (5) / (6) | curl could not resolve the proxy / target host. Check the hostname named in the error. |
| curl: (7) / (28) | Connection failure / timeout. Keep the full message to locate the stage. |
| curl: (35) / (60) | TLS connection / certificate verification failure. Inspect the TLS checks below. |
| http_code=000 | No HTTP response code was available to curl. 000 is diagnostic output, not a status returned by the API. |
| HTTP 401 or another HTTP status | You reached an HTTP responder. A gateway authentication rejection is compatible with this key-free probe; inspect headers and body before attributing the response. |
| HTTP redirect or an unexpected HTML page | Record the Location header and page type. Check the hostname, network and proxy path before sending credentials. |
Separate TLS, proxy and app differences
For certificate failures, first verify the device clock and the configured hostname, then update the app or runtime's trusted certificate store through its supported process. On a managed network, ask IT to verify the inspection certificate and trust configuration. A certificate error identifies a failed verification, not who caused it.
curl works, but the app fails
Compare the app's saved URL, proxy choice, runtime version and trust store. A desktop app and a terminal may inherit different settings. Reproduce with the same network before treating the result as an upstream outage.
Only one network fails
Record the region, carrier or corporate network, time, DNS answers and error stage on both networks. This narrows the scope; it does not by itself identify a responsible party. The remote_ip printed by curl may be a proxy or edge address.
The app received HTTP, then disconnected
You have passed the initial connection stage. Preserve any output and request_id, and use the streaming guide to check the terminal event. An HTTP 200 or successful model-list fetch does not establish that a model generation completed.
Collect evidence that support can use
After you can reach the expected HTTPS service, follow the client's integration guide for one authenticated text request and match the result with Dashboard → Logs. If the problem persists, send this small evidence set through the contact page:
- Time and timezone; device OS; app name and version; affected region and network.
- Configured hostname and API path, selected protocol and exact model ID, with any credentials or private query parameters removed.
- Exact error code and message; HTTP status, response type and request_id if present. A failure before HTTP may have no request_id.
- DNS result and key-free curl result; whether a second network or another client behaves differently.
- Do not include API keys, Authorization headers, cookies, proxy passwords or private prompts. Redact these before sharing screenshots or logs.
Scope and sources
Reviewed September 9, 2026 against the URL Standard, Node.js and libuv error documentation, and curl's command and certificate documentation linked below. The commands are diagnostic recipes, not a live availability report. A successful connectivity probe verifies only its own device, network, hostname and request at that time.
Connection troubleshooting FAQ
Does Failed to construct 'URL': Invalid URL mean my API key is wrong?
The message points to URL construction. Check the client field for malformed text, an empty base or a duplicated scheme first. Authentication can be tested after the client constructs the intended URL and receives an HTTP response.
Why can I open router.one while api.router.one returns ENOTFOUND?
They are separate hostnames, and the browser and API client may use different DNS or proxy settings. Test the API hostname on the affected device and compare the app with the key-free probe before changing billing or model settings.
Does an empty Dashboard → Logs prove the gateway was never reached?
No. It is consistent with a failure before HTTP, but filters, recording delays or a request rejected before a normal usage record can also explain it. Keep the client error, time and request_id if present so support can correlate the evidence.
Does HTTP 200 mean my model request succeeded?
It confirms an HTTP response, not a completed generation. This guide's model-list probe does not invoke a model. For a generation, inspect its final response or stream terminal event, usage and matching request record.