API timeout vs DNS error
What is an API timeout?
An API timeout happens when your application sends a request and the server doesn't respond within the allowed time. The key thing to understand is that the connection was established — the server was found and contacted — but it was too slow to reply. This is fundamentally different from a DNS error.
Timeouts are usually configured on the client side. For example, if your HTTP client has a 10-second timeout and the server takes 15 seconds to respond, you'll get a timeout error even though the server was working — just slowly.
Common timeout error messages look like this:
Timeout causes include server overload, network congestion, large request or response payloads, serverless cold starts, and firewall rules that silently drop packets instead of rejecting them.
What is a DNS error?
A DNS error means the very first step of the connection failed: translating the domain name (like api.example.com) into an IP address. Without this step, no connection is even attempted. Your request never leaves your network because the system doesn't know where to send it.
DNS errors are typically fast. They usually fail in under a second because the DNS resolver quickly determines it can't find the domain. This speed is a useful diagnostic signal.
Common DNS error messages look like this:
DNS errors can be caused by: a typo in the domain name, a down or misconfigured DNS server, DNS propagation delays after a domain change, firewall or corporate proxy blocking DNS queries, or the domain genuinely not existing.
How to tell which one you have
The quickest way to distinguish a timeout from a DNS error is to look at two things: the error message and how long it takes to fail.
- DNS errors fail fast (under 1–2 seconds) and mention "DNS", "ENOTFOUND", "getaddrinfo", or "could not resolve host".
- Timeouts fail slow (5–30+ seconds) and mention "timeout", "ETIMEDOUT", or "aborted".
- Connection refused is a third category — it fails fast but means DNS succeeded. The server was found but actively rejected the connection (wrong port, service not running).
The checker tool above gives you a precise breakdown. When you test a URL, it reports the DNS resolution time, TLS handshake time, and HTTP response time separately. If DNS shows a failure, you have a DNS problem. If DNS succeeds but the total time is very high or the request never completes, you have a timeout.
For a deeper walkthrough of each diagnostic step, see our complete guide to checking if an API is down.
Actionable troubleshooting steps
Once you've identified whether you're dealing with a DNS error or a timeout, here's what to do next.
If it's a DNS error:
- Double-check the domain name for typos
- Try a different DNS resolver: set your DNS to 8.8.8.8 (Google) or 1.1.1.1 (Cloudflare)
- Flush your local DNS cache (on macOS:
sudo dscacheutil -flushcache, on Windows:ipconfig /flushdns) - Check if the domain resolves from another network (phone hotspot, VPN)
- If the domain was recently created or changed, wait for DNS propagation (up to 48 hours)
If it's a timeout:
- Check if the service has a status page — it might be a known outage
- Test from a different network to rule out local routing issues
- Increase your client-side timeout temporarily to see if the server responds at all
- Check if a firewall or proxy is silently dropping your packets
- Implement retry logic with exponential backoff for production resilience
Quick diagnosis checklist
- Check if the error message mentions 'DNS', 'ENOTFOUND', or 'getaddrinfo'
- Note how long the error takes to appear — fast (<1s) suggests DNS, slow (10s+) suggests timeout
- Try resolving the domain with nslookup or dig to isolate DNS
- Test from a different network or DNS resolver (8.8.8.8, 1.1.1.1)
- Use the checker tool to see the full DNS → TLS → HTTP breakdown
- If DNS resolves fine, check firewall rules and server availability
Frequently asked questions
What is the difference between a timeout and a DNS error?
A DNS error means your system couldn't translate the domain name into an IP address — the request never left your network. A timeout means the DNS lookup succeeded and a connection attempt was made, but the server didn't respond in time. They fail at different stages of the network stack.
How can I tell if my API error is a DNS problem?
DNS errors typically fail very fast (under 1 second) and produce specific error messages like 'ENOTFOUND', 'getaddrinfo failed', or 'DNS resolution failed'. If your error takes 10+ seconds to appear, it's more likely a timeout, not a DNS issue.
Why does my API request time out?
API timeouts happen when the server is too slow to respond. Common causes include server overload, network congestion, large payloads, cold starts in serverless environments, or firewall rules silently dropping packets. The server received the request but couldn't process it in time.
Can a DNS error look like a timeout?
Rarely. DNS queries have their own timeout (usually 1-5 seconds), and most DNS libraries will retry with a backup resolver before giving up. A slow DNS lookup might add 2-3 seconds, but it will still produce a clear DNS-specific error, not a generic timeout.
How do I fix a DNS resolution error?
First, try a different DNS resolver (like 8.8.8.8 or 1.1.1.1). Flush your local DNS cache. Check if the domain exists by looking it up with nslookup or dig. If the domain resolves from other networks but not yours, the issue is with your DNS configuration or provider.
How do I fix an API timeout?
Increase your client-side timeout if it's too aggressive. Check the server's health and load. Try the request from a different network to rule out routing issues. If the API is a third-party service, check their status page. Implement retry logic with exponential backoff for resilience.
What tools can I use to diagnose DNS vs timeout issues?
Use 'nslookup' or 'dig' to test DNS resolution. Use 'curl -v' to see connection timing. Use this tool to get a full breakdown of DNS, TLS, and HTTP timing for any URL. The diagnostics section shows exactly where the failure occurred.