OpenAI API Connection Error: Fix APIConnectionError by Testing the Route First

openai.APIConnectionError: Connection error. means the Python SDK encountered a connection or transport failure rather than returning an ordinary API status error. Capture the underlying exception, then test the exact host and network configuration from the process that failed. DNS, certificate trust, proxy settings, outbound access, and the configured endpoint are the first checks. Changing your prompt or buying credits does not repair those failures.

A timeout needs more care: the request may have been sent, with the response delayed or lost. Neither a missing request ID nor an APIConnectionError proves that OpenAI did no processing or that the request incurred no usage. Keep the original operation's state before deciding whether to retry.

OpenAI's error-code guide identifies network settings, proxies, SSL certificates, firewalls, and container permissions as connection-error checks. The SDK details below follow the current Python reference and Node/TypeScript reference, checked on October 6, 2026. Match examples to your installed SDK and runtime.

Read the Response Evidence First

Start with one failed attempt, outside any automatic retry loop if possible. Record the exception class, its underlying cause, elapsed time, effective endpoint, and any returned HTTP status or request ID. Then choose the next action:

Python maps returned HTTP errors to APIStatusError subclasses, with status_code, response, and request-ID access. A generic connection exception does not supply the same evidence. See the Python error-handling documentation.

For a returned 429, follow the OpenAI API rate-limit guide when the response identifies temporary request or token pressure. If it identifies insufficient_quota or a billing restriction, use the quota troubleshooting guide. Continue connection debugging when the actual failure is in the transport, rather than classifying everything by a wrapper's “API error” message.

Run the Same-Path Test Where the Application Fails

A successful laptop request does not clear a failing Kubernetes worker, serverless function, or background job. Use the same running environment, hostname, outbound proxy, certificate configuration, and API base URL. A shell inside the same container helps, but it can still use a different resolver or HTTP client from the Python or Node process.

1. Identify the destination actually selected by the application. Inspect the configured client's base URL and provider selection, including any explicit override. Record the host and endpoint without secrets. A direct OpenAI URL, an Azure resource, and a gateway are separate destinations.
2. Capture one underlying failure in that application process. A resolver error calls for DNS checks; a certificate error calls for trust-chain checks; a proxy handshake error calls for the proxy path. Avoid making several unrelated changes at once.
3. Run a bounded HTTP probe to the approved destination. Compare its result with the SDK failure, then examine the differences between curl and the application's client.
4. Check the appropriate provider's status page at the time of the incident. For direct OpenAI, use status.openai.com. An operational status page does not establish that your local network path is healthy; a recorded incident also does not prove it caused this request's failure.

This curl example checks the direct OpenAI host without an API key or inference request. For Azure or a gateway, replace the URL with a known, approved public path on that provider's exact hostname. Do not send OpenAI credentials to a host merely because it accepts an OpenAI-shaped API.

probe_url='https://api.openai.com/v1/models'
curl -q --connect-timeout 5 --max-time 15 \
  --silent --show-error --output /dev/null \
  --write-out 'http=%{http_code}\n' "$probe_url"
probe_exit=$?
printf 'curl_exit=%s\n' "$probe_exit"

-q is deliberately the first curl argument: it suppresses the default curl configuration file. It does not suppress proxy environment settings. TLS verification stays enabled. The connection timeout covers connection establishment, including DNS and TLS; --max-time bounds the entire probe. These controls and exit-code meanings are documented in the curl manual.

Read both results. Without --fail, curl can exit successfully after receiving an HTTP 401, 429, or 503. A returned HTTP code establishes that this probe received a response, not that inference works. Confirm which service answered: a corporate proxy or gateway can produce its own response. http=000 means curl did not observe an HTTP response code for this probe; it says nothing conclusive about a different request's processing or billing.

Use the failure to choose a fix

These curl codes identify failure categories, not a unique root cause. Keep the cause and timing from the SDK alongside the probe result. A new HTTP response after a DNS correction is useful progress even if it now reveals a separate authentication problem.

For corporate TLS inspection, obtain the approved CA certificate through your organization's normal process and configure the HTTP client's trusted context. Do not use verify=False, insecure curl options, an arbitrary downloaded certificate, or a hardcoded destination IP as a repair. They change the security properties or routing assumptions of the request.

Why It Works Locally but Fails When Deployed

Compare the running worker with the environment that succeeded. Focus on the effective base URL, SDK/dependency versions, proxy transport, CA bundle, resolver, region, outbound access, and client lifetime. Build-time package downloads do not demonstrate that a deployed function can reach the API at runtime.

If curl works in the container while the app fails, investigate the application's resolver and transport rather than declaring the network fixed. A February 2024 OpenAI Community report describes a Flask application that worked locally but failed in Kubernetes. The poster traced a DNS timeout to the application's gunicorn/eventlet/dnspython combination despite separate pod-level checks, and reported success after a dependency downgrade. That is a historical, self-reported case; it is a reason to inspect the executing process, not a general instruction to pin dnspython to that version.

Apply an identified configuration correction to the worker that makes the call. Restart or redeploy only when needed for that configuration to take effect, then confirm the new value in the running process. Editing a local file while an old worker keeps running can leave the original failure unchanged.

For async Python applications, also check whether an HTTP client is reused across incompatible event-loop lifetimes or closed too early. Reuse a client within its intended application scope and close it before the loop shuts down. The Python client documentation covers explicit closing and context-manager use. Rebuilding a client on every error can conceal a lifecycle defect while creating additional connection overhead.

Use SDK Controls Without Hiding Evidence

Temporarily disabling SDK retries makes one attempted request easier to trace. The current Python and Node SDKs retry eligible failures twice by default, including connection failures and certain returned statuses. Application, queue, and gateway retries can multiply those attempts. Use one bounded policy after diagnosis rather than adding an unlimited outer loop. See the Python and Node retry documentation.

Python: catch timeouts before their connection-error parent

In the current Python SDK, APITimeoutError is a subclass of APIConnectionError. Catch it first or the broader handler will consume it. __cause__ exposes the underlying exception for inspection. This function wraps one existing synchronous, non-streaming operation; operation should be your normal SDK call. It does not configure credentials or retry the call.

import openai


def diagnose_once(operation):
    try:
        result = operation()
    except openai.APITimeoutError as exc:
        print("timeout", type(exc.__cause__).__name__)
        raise
    except openai.APIConnectionError as exc:
        print("connection", type(exc.__cause__).__name__)
        raise
    except openai.APIStatusError as exc:
        print("api_status", exc.status_code, exc.request_id)
        raise
    else:
        print("success", getattr(result, "_request_id", None))
        return result

Inspect the cause locally before choosing a repair; only its class name is printed here to avoid dumping exception messages that may contain sensitive URLs. Save a sanitized message when the class alone is insufficient. Custom transport or hook exceptions can propagate unchanged, so preserve an unfamiliar exception instead of relabeling every failure as APIConnectionError.

For diagnostic construction, use max_retries=0 and an explicit timeout appropriate to the workload. Python's numeric timeout is in seconds; the current documented default is ten minutes. A short diagnostic deadline is an example choice, not a recommended universal production limit. If connection succeeds but legitimate generation takes longer, adjust the response-read deadline within the application's total budget. Increasing a read timeout cannot fix a bad hostname or untrusted certificate.

Version check: the current Python reference documents HTTPX2, httpx2.Timeout, and DefaultHttpx2Client for custom timeout, proxy, and TLS configuration. Older installations may use HTTPX and different factory names. Check the SDK version in the failing environment and use its supported transport. With the current client, an approved proxy and a trusted ssl.SSLContext belong in the documented custom HTTP client; do not patch the SDK's private _base_client or blindly paste HTTPX2 names into an older environment.

Node: use milliseconds and the matching fetch implementation

Node's corresponding timeout class is APIConnectionTimeoutError. Its numeric timeout is in milliseconds, unlike Python's seconds. The current default is also ten minutes; maxRetries: 0 disables SDK retries for diagnosis. Use the Node reference for the installed version's error and timeout controls.

For a Node application using an approved HTTP proxy, the current documentation pairs Undici's fetch with its ProxyAgent. The dispatcher must belong to the fetch implementation that uses it. This is a configuration pattern, not a connectivity test; it requires the compatible openai and undici packages plus the reader's approved environment settings.

import OpenAI from "openai";
import { fetch as undiciFetch, ProxyAgent } from "undici";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  fetch: undiciFetch,
  fetchOptions: {
    dispatcher: new ProxyAgent(process.env.APPROVED_PROXY_URL),
  },
  maxRetries: 0,
  timeout: 30_000,
});

Set the proxy URL only from your trusted configuration; handle any embedded proxy credentials as secrets. When no proxy is required, omit this custom proxy configuration. Do not pair an Undici dispatcher with an unrelated fetch implementation or assume every runtime automatically honors HTTPS_PROXY. Bun and Deno use different proxy options, documented in the same reference. Copying an older httpAgent example across these runtimes can configure the wrong transport.

For returned errors, preserve status and request_id from the SDK error. On success, the SDK exposes _request_id, with raw-response access available through .withResponse(). Inspect the timeout class before the broader connection class when classifying errors. An AbortSignal can cancel the local request or response-body read; it does not establish that the server reversed processing or usage.

Keep streaming failures separate from request setup

A stream can start successfully and fail while the application reads it. Record whether any events or output arrived, when reading stopped, and whether downstream actions already occurred. In the current Python SDK's Stream/AsyncStream, read timeouts become APITimeoutError and other HTTP request failures become APIConnectionError; stream consumption is not automatically replayed. Assistants streaming and raw .with_streaming_response retain different prior behavior. See the Python streaming documentation.

Do not resend a partially consumed stream just because the connection error appears retryable. First decide whether repeating the operation can duplicate visible output, tool actions, or other side effects. A non-streaming diagnostic wrapper also cannot catch a failure that happens later, outside the wrapper, while iterating the returned stream. Handle and record errors around consumption itself.

Route Branches That Change the Fix

For direct OpenAI, establish the path to the configured OpenAI endpoint and separate any returned API status from transport failure. For Azure OpenAI, verify the actual resource endpoint, deployment, API version, authentication method, and resource network rules. For an OpenAI-compatible gateway, inspect that provider's endpoint and proxy logs first. A working call through a different provider establishes an alternative path, not the cause of the original failure.

Browser-side calls need a separate check: the browser can block a request through CORS or its own networking restrictions before a backend SDK becomes involved. Keep API credentials on the server and capture the browser's actual error plus the application's backend response. Moving a secret into client-side code is not a connection fix.

Messages such as no route-compatible authentication source is configured for openai or this turn ended before a reply need the integration's own context. Their wording alone does not establish an official SDK transport failure. If logs show that the integration could not select credentials before dispatch, repair that integration's approved provider and credential selection before testing the API connection. If it dispatched a request, capture the underlying SDK or HTTP result. Likewise, a message about rebuilding a client and waiting six seconds describes that application's retry behavior; it does not establish a universal OpenAI recovery interval.

What Proves the Fix—and What to Send Support

A returned response from the unauthenticated curl probe is the first checkpoint. The second is one small, valid request through the failing application's original provider, endpoint, project, model, and transport. Use authorized credentials already intended for that service. This is a real operation and may incur usage charges. A successful model-list request alone does not exercise the inference workload.

If that request succeeds, restore the actual request shape with controlled traffic: its input size, output budget, streaming mode, and relevant concurrency. Watch complete responses, deadlines, and the original underlying error. A small non-streaming request can pass while a longer stream still exceeds a proxy idle timeout. If only the separate test works, compare its effective configuration with the worker before declaring recovery.

Preserve ambiguous operations for reconciliation instead of blindly replaying them. For direct OpenAI, request-debugging documentation describes x-request-id and an explicitly supplied X-Client-Request-Id. The latter can help support look up whether a supported request was received when the server ID is unavailable. Supply a unique ASCII value of at most 512 characters; the SDK does not automatically add it. It is a correlation identifier, not an idempotency key or a billing guarantee.

For escalation, provide the timestamp and timezone, destination host and endpoint, SDK/runtime versions, region, exception class and sanitized cause, elapsed time, any returned status/request ID, and the point where the same-runtime checks changed. Describe the configuration correction and its result. Share selected diagnostics rather than full headers, bodies, API keys, proxy passwords, or customer inputs. A statement such as “TLS succeeds after loading the approved CA, but the worker still times out while reading the stream” gives support a concrete next investigation.

The examples here are documentation-based patterns checked offline for syntax and selected behavior. They are not results from a live authenticated API call or proof of recovery in your environment.

FAQ

Does APIConnectionError mean OpenAI is down?

No. It identifies a transport failure in the SDK call, which can involve DNS, TLS, a proxy, outbound access, or a response-read problem. Check the OpenAI status page alongside the same-runtime cause; neither the exception nor a green status page identifies the cause by itself.

Why is there no request ID? Was the request free?

A response may never have reached your client, or it may have been lost after the request was sent. A missing ID does not prove no processing or no charge. Keep the operation's state and, for supported direct OpenAI endpoints, use an explicitly supplied client request ID for future correlation as described in the request-debugging reference.

Should I rotate my API key to fix a connection error?

First inspect the actual exception or returned response. Key replacement cannot repair DNS, TLS, or a failed proxy handshake. A returned authentication error calls for credential checks on the service that answered; key rotation is appropriate when there is a credential or security reason, not as a substitute for identifying that service.

Curl works, but the SDK still says “Connection error.” What next?

Compare the SDK process's resolver, fetch/HTTP transport, proxy configuration, trusted CA, base URL, and timeout with curl's. Then run one bounded SDK attempt with retries disabled and inspect the cause. Curl's HTTP response proves only its own probe reached a responding service; it does not validate the SDK's settings, account, model, or stream.