API Timeout Debugging Guide
Debug API timeouts by separating client timeout, DNS, TLS, gateway, upstream service, database and retry behavior. This Formalint reference is written for working developers, DBAs and support engineers who need a repeatable debugging path instead of a one-line snippet with no context.
Use the notes below as a practical review order: understand the input, capture evidence, make one small change and verify the result before moving to the next assumption.
When to use this page
Turn vague timeout reports into ordered evidence. It is most useful when a small validation or debugging mistake can create noisy tickets, misleading logs or hard-to-review production changes.
Practical workflow
| Step | What to confirm |
|---|---|
| Measure phases | Separate DNS, TCP connect, TLS negotiation, first byte and total time. |
| Find the owner | A timeout may belong to the browser, API client, CDN, proxy, service or database. |
| Control retries | Make sure clients do not multiply load while the system is already slow. |
curl timing template
curl -o /dev/null -s -w \
"dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} start=%{time_starttransfer} total=%{time_total}\n" \
https://api.example.com/healthReview checklist
- Record the exact timeout value and which layer set it.
- Compare health checks with the slow endpoint.
- Check gateway logs and upstream service logs with the same timestamp.
- Look for database locks, slow queries and exhausted connection pools.
- Avoid raising every timeout before understanding the bottleneck.
Common mistake
Increasing the timeout can hide the symptom while users still wait too long. The useful question is where the time is being spent.
Formalint is strongest when the page helps the developer decide what the tool cannot prove. Treat every formatter, regex and command as one layer of evidence, not the whole truth.
Frequently asked questions
Is a 504 the same as a timeout?
A 504 is a gateway reporting that an upstream did not respond in time. The root cause may be deeper.
Should clients retry timeouts?
Only when the operation is safe to repeat or has an idempotency key.
Related Formalint references
Continue with Nginx 502 504 Debugging, API Idempotency Retry Guide, PostgreSQL Lock Debugging.