APIConnectionError
openai.error.APIConnectionError
Stack trace
openai.error.APIConnectionError: Connection to OpenAI API timed out after 10 seconds
File "/usr/local/lib/python3.9/site-packages/openai/api_requestor.py", line 123, in request
raise APIConnectionError("Connection to OpenAI API timed out")
openai.error.APIConnectionError: Connection to OpenAI API timed out Why it happens
This error happens when the network request to OpenAI's API endpoint exceeds the configured timeout duration, often due to slow or unstable internet connections, firewall restrictions, or DNS resolution issues. The client library raises APIConnectionError to indicate it could not complete the HTTP request in time.
Detection
Monitor your application's logs for APIConnectionError exceptions and track network latency metrics to detect connection timeouts before they impact user experience.
Causes & fixes
Network connectivity issues such as unstable internet or firewall blocking outbound requests
Ensure your server or local machine has stable internet access and that firewalls or proxies allow outbound HTTPS requests to api.openai.com on port 443.
Default timeout setting too low for your network conditions
Increase the timeout parameter in the OpenAI client configuration to allow more time for the request to complete.
DNS resolution delays or misconfiguration causing slow API endpoint lookup
Verify DNS settings and consider using a reliable DNS provider or caching DNS results to reduce lookup latency.
Code: broken vs fixed
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello"}]
) # This line may raise APIConnectionError due to timeoutimport os
from openai import OpenAI
client = OpenAI(timeout=30) # Increased timeout to 30 seconds
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello"}]
)
print(response) # Now works with longer timeout and stable connectionWorkaround
Wrap API calls in try/except for APIConnectionError and implement exponential backoff retries to handle intermittent network timeouts gracefully.
Prevention
Use robust network infrastructure with reliable DNS and firewall configurations, and configure appropriate client timeouts and retry logic to avoid connection timeouts.