Summary: Use curl to save response headers and body first, then isolate HTTP API problems by status code, timing, and request headers.
When debugging an API, preserve the scene with: curl -sS -D headers.txt URL -o body.txt. This shows the status code and response headers without mixing the body with diagnostic output.
Make a reproducible request
curl -sS -D headers.txt https://api.example.test/health -o body.txt
printf 'status: '; sed -n '1p' headers.txt
cat body.txt-sS keeps error output, -D writes response headers, and -o saves the body. Do not add -f on the first run, because it can suppress error response bodies and leave you with fewer clues.[1]
Filter by status code and timing
curl -sS -o /tmp/body -w 'status=%{http_code} time=%{time_total}s size=%{size_download}
' https://api.example.test/health2xx usually means the request was processed successfully; for 4xx, check the URL, parameters, auth, and HTTP method first; for 5xx, record the server time and request ID at the same time. Status-code semantics are summarized in the HTTP overview.[2]
Check request headers and method
curl -sS -H 'Accept: application/json' -H 'X-Request-ID: debug-001' https://api.example.test/items
curl -sS -X POST -H 'Content-Type: application/json' --data '{"name":"demo"}' https://api.example.test/itemsAdd headers only to verify the API contract, and never write tokens into shell history or articles. Use -v to see what is actually sent, but it can expose credentials, so scrub logs before sharing.[1]
Handle redirects, timeouts, and TLS
curl -sS -L --connect-timeout 5 --max-time 15 -w '
final=%{url_effective} status=%{http_code}
' https://api.example.test/redirect
curl -v https://api.example.test/health 2>curl-trace.log-L follows redirects, and timeout flags bound connection and total transfer time. If TLS fails, do not bypass it with -k and draw conclusions; confirm the certificate chain, hostname, and system clock first. -k is for isolated testing only, not a production fix.
Troubleshooting checklist and rollback
| Symptom | Check first | Action |
|---|---|---|
| Host resolution failure | DNS line in curl -v |
Check DNS, proxy, and hosts |
| Connection timeout | Connection-phase timing | Verify port, firewall, and proxy |
| 401/403 | Response headers and auth scheme | Get least-privilege credentials again |
| Certificate error | TLS diagnostics | Fix the cert chain; do not disable verification |
Rolling back means deleting the debug files: rm -f headers.txt body.txt curl-trace.log /tmp/body. If a command wrote data to the server, use the API-provided delete or revoke endpoint to clean it up; curl will not roll back business side effects for you.
Limits and test notes
This article only verified GET, response headers, body, and status/timing output against a local HTTP mock. It did not perform end-to-end testing of real HTTPS, auth services, proxies, or HTTP/2. For live debugging, also record the time, target environment, and request ID.
FAQ
Why not -s? -sS stays quiet while preserving error output.
When to use -f? Only in CI when you only care about the failure exit code, and still save the response body.
What can -v leak? Potentially sensitive fields like Cookie and Authorization. Scrub before sharing.
References
- [1] curl command line tool manual (curl manual)
- [2] An overview of HTTP (MDN HTTP)
Main commands were tested on WSL Ubuntu 24.04; some entries were only cross-checked against official docs and not executed live.
