Troubleshoot a connection

Check the public origin, TLS and free catalog before spending credits on a probe.

Set BASE_URL to your HTTPS API origin without a trailing slash or /v1, and pass API_KEY from your credential store. OpenAI-compatible SDKs use ${BASE_URL}/v1; Anthropic-compatible SDKs use BASE_URL.

Use the exact public origin for the chosen protocol: ${BASE_URL}/v1 for an OpenAI-compatible client; BASE_URL for an Anthropic-compatible client. Do not copy a URL that contains a key. Check the network before generation: reading the model catalog does not debit credits.

Free checks first

Send GET /healthz to BASE_URL. A response with status ok confirms that the HTTP service is reachable. Check access to a specific model separately.
Check that the client uses HTTPS and the right base URL. The Messages endpoint itself is /v1/messages even though its base URL has no /v1.
Use GET /v1/models with the key to separate network, authentication and catalog problems.
If a client fails while curl succeeds, compare its configured protocol, model ID and credential source with client compatibility.
Run doctor for free client checks. Only an explicit --probe --yes can make a paid inference check.

Separate connectivity from access

bash

curl -i --max-time 10 "$BASE_URL/healthz"
printf 'Authorization: Bearer %s\n' "$API_KEY" \
  | curl -q -H @- -i --max-time 10 "$BASE_URL/v1/models"

The first command should return HTTP 200 and {"status":"ok"}. This confirms that the public service responds; it does not verify your key, model availability or a generation request. The second checks HTTPS, your key, and catalog access together. HTTP 200 with data confirms the service can use the key; 401 or 403 leads to authentication, while 404 for a particular model ID leads to the catalog. Neither free check proves that a paid model request will succeed. Do not put a secret-expanded command in a report or screenshot.

Observation	Next check
DNS fails or no connection opens	Check DNS, proxy settings, and outbound HTTPS access to the public hostname. Keep the time and secret-free client error.
TLS validation fails	Check the device clock and trusted certificate store, including a managed proxy. Do not disable certificate verification.
`/healthz` works but the catalog returns 401/403	Check the Bearer header, key expiry, organization, and permissions. A new paid generation will not fix authentication.
The catalog works but the AI client does not	Compare base URL, protocol, canonical model ID, and credential delivery with client compatibility.
The API responds but a stream disconnects	Read the last SSE event and check the client's timeout. Keep the same idempotency key until you decide whether to retry.

If DNS or TLS fails, do not disable certificate validation to proceed. Report the public hostname, time, safe error code and request ID if one exists. For a request that reached the API but failed, see error recovery.