Localizes a failed API or network call to DNS, TCP, TLS, HTTP, or the app from the exact status, timeout, or errno (ENOTFOUND, ECONNREFUSED, 429, 502/503). Use when curl/fetch fails, the API looks down, or errors are intermittent. Not for Spark shuffle slowness, Android jank traces, or rewriting retry/backoff before the failing layer is known.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Localizes a failed API or network call to DNS, TCP, TLS, HTTP, or the app from the exact status, timeout, or errno (ENOTFOUND, ECONNREFUSED, 429, 502/503). Use when curl/fetch fails, the API looks down, or errors are intermittent. Not for Spark shuffle slowness, Android jank traces, or rewriting retry/backoff before the failing layer is known.
version
1.0.1
risk
safe
source
opus-skills-library
date_added
2026-05-27
domain
troubleshooting
kind
leaf
tags
["network","api","http","timeouts","dns","tls"]
Network & API Failure Triage
A network or API failure hides behind a status code or a timeout, and "the API is down" is rarely the whole truth. Triage localizes which layer failed — DNS, TCP, TLS, HTTP, or the application — and reads the exact failure, because each layer points to a completely different fix.
When to Use
Use this skill when:
An API call fails, times out, or returns an unexpected error status (4xx/5xx).
You see connectivity errors: ECONNREFUSED, ECONNRESET, ENOTFOUND, ETIMEDOUT, getaddrinfo ENOTFOUND.
A request works intermittently or only from certain hosts/regions.
You need to distinguish a client bug from a server outage from a network problem.
Someone reports "the API is down" and you need to find the actual failing layer.
A shell with curl available (Windows PowerShell, WSL, or Git Bash).
openssl for TLS handshake checks (included in Git for Windows and WSL).
nslookup or Resolve-DnsName for DNS checks (built into Windows).
Test-NetConnection for TCP reachability checks (built into Windows PowerShell).
Network egress to the target host (or awareness that a proxy/VPN is required).
No live secrets in commands — use YOUR_KEY placeholders when testing authenticated endpoints.
Procedure
Step 1 — Capture the exact error before guessing
Before running any diagnostic, record the raw error message, status code, and timeout type. Do not paraphrase "the API is down" — get the exact string.
# Capture the full error from your application or test call
# Example: note the exact status, headers, and body
curl -v -s -o NUL -w "HTTP %{http_code} | connect=%{time_connect}s | tls=%{time_appconnect}s | total=%{time_total}s\n" https://api.example.com/health
If the error is a stack trace (ECONNREFUSED, ENOTFOUND, ETIMEDOUT, ECONNRESET), note the error code — it tells you the layer immediately.
Step 2 — Localize the failing layer (walk the stack bottom-up)
Test each layer in order. Stop at the first layer that fails — that is your primary suspect. Do not skip ahead.
Layer 1: DNS — does the name resolve?
# Windows PowerShell
Resolve-DnsName api.example.com
# Or classic nslookup
nslookup api.example.com
# WSL / Git Bash
dig +short api.example.com
dig api.example.com ANY
What to check:
Does it resolve at all? ENOTFOUND / NXDOMAIN = DNS failure.
Does it resolve to the expected IP? Stale records, wrong TTL, split-horizon DNS.
Does it resolve differently from the failing host vs your machine? Check from the actual environment.
If DNS fails: fix records, check /etc/hosts or C:\Windows\System32\drivers\etc\hosts, verify DNS server, check TTL for stale cache.
Layer 2: TCP — does the connection open?
# Windows PowerShell
Test-NetConnection -ComputerName api.example.com -Port 443
# WSL / Git Bash
nc -zv api.example.com 443
# Or with timeout
nc -zv -w 5 api.example.com 443
What to check:
TcpTestSucceeded: True — port is reachable.
TcpTestSucceeded: False — firewall, wrong port, host down, or service not listening.
Correlate failures to a specific instance, region, or pod — partial outages masquerade as flakiness.
Check for recent DNS/LB changes, deployments, or cert rotations that coincide with the start of failures.
Compare success rate across instances/regions to isolate the failing subset.
Step 5 — Correlate across services
For multi-service failures, use log-correlation-across-services to trace a request ID across service boundaries and pinpoint where the chain breaks.
Pitfalls
"The API is down" with no layer localization — the fault is often DNS, TLS, or one bad instance behind a load balancer. Always walk the stack before concluding the server is down.
Retry storms — aggressive retries on a struggling dependency amplify the outage. A 5-second blip becomes a 5-minute collapse when every client retries at once.
Retrying non-idempotent calls — blind retries on POST/PATCH create duplicate writes, duplicate charges, duplicate emails. Check idempotency before retrying.
Ignoring 429 — hammering through a rate limit instead of backing off makes the rate limit worse, not better.
Cert blindness — an expired TLS certificate is a common root cause that is invisible if you skip the TLS layer check. Always run openssl s_client when handshakes fail.
Confusing connect timeout with read timeout — they have completely different causes and fixes. Connect timeout = network/service down. Read timeout = server slow/overloaded.
Testing from your machine, not the failing environment — DNS split-horizon, firewall rules, and proxy configs differ by environment. Reproduce from the actual failing host.
Assuming 502/504 means the origin is down — it means the gateway could not reach the origin. The origin might be up but slow, or the gateway config might be wrong.
Stale DNS cache — Windows DNS cache (ipconfig /displaydns) can serve old records past TTL. Flush with ipconfig /flushdns when DNS changes are suspected.
Verification
Confirm the triage is complete by checking every item:
# 1. Verify DNS resolves to expected IP
Resolve-DnsName api.example.com
# 2. Verify TCP port is reachable
Test-NetConnection -ComputerName api.example.com -Port 443
# 3. Verify TLS handshake and cert validity
openssl s_client -connect api.example.com:443 -servername api.example.com < NUL 2>NUL | openssl x509 -noout -dates
# 4. Verify HTTP returns expected status
curl -v -s -o NUL -w "HTTP %{http_code}\n" https://api.example.com/health
# 5. Flush DNS cache if DNS changes were made
ipconfig /flushdns
