How to use cURL for API debugging and troubleshooting?

Debugging and troubleshooting are important use cases for cURL. Mastering debugging techniques helps quickly identify network request issues, API failures, and performance bottlenecks.

Basic Debugging Parameters

bash
# Show verbose information (most commonly used)
curl -v https://api.example.com

# Show only response headers
curl -I https://api.example.com

# Show response headers and body
curl -i https://api.example.com

# Silent mode (no progress)
curl -s https://api.example.com

# Show error messages
curl -S https://api.example.com

Verbose Output Mode

bash
# -v shows complete request and response process
curl -v https://api.example.com/users

# Output explanation:
# > indicates sent request line and headers
# < indicates received response headers
# * indicates connection and SSL handshake info

# More detailed debug info
curl --trace-ascii debug.log https://api.example.com

# Hexadecimal format output
curl --trace debug.hex https://api.example.com

Response Time Analysis

bash
# Show transfer statistics
curl -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
     -o /dev/null -s https://api.example.com

# Complete performance analysis
curl -w "DNS Lookup: %{time_namelookup}s\nTCP Connect: %{time_connect}s\nSSL Handshake: %{time_appconnect}s\nFirst Byte: %{time_starttransfer}s\nTotal Time: %{time_total}s\nDownload Size: %{size_download}bytes\nDownload Speed: %{speed_download}bytes/s\n" \
     -o /dev/null -s https://api.example.com

# Output to file
curl -w "@curl-format.txt" -o /dev/null -s https://api.example.com

Common Debug Variables

Variable	Description
time_namelookup	DNS resolution time
time_connect	TCP connection time
time_appconnect	SSL/SSH handshake time
time_starttransfer	Time to first byte (TTFB)
time_total	Total time
size_download	Download size
speed_download	Download speed
http_code	HTTP status code

Error Troubleshooting Techniques

bash
# 1. Check HTTP status code
curl -w "\nHTTP Status: %{http_code}\n" -o /dev/null -s https://api.example.com

# 2. Check redirect chain
curl -L -v https://example.com 2>&1 | grep -E "(< HTTP|< Location)"

# 3. Check SSL certificate
curl -v https://api.example.com 2>&1 | grep -A 10 "SSL connection"

# 4. Ignore SSL certificate verification (testing only)
curl -k https://self-signed.badssl.com

# 5. Set timeout
curl --connect-timeout 5 --max-time 10 https://api.example.com

# 6. Retry mechanism
curl --retry 3 --retry-delay 2 https://api.example.com

Network Diagnostics

bash
# Test connectivity
curl -v telnet://example.com:80

# Check proxy settings
curl -v --proxy http://proxy.example.com:8080 https://api.example.com

# Specify DNS server
curl --dns-servers 8.8.8.8 https://api.example.com

# Force IPv4
curl -4 https://api.example.com

# Force IPv6
curl -6 https://api.example.com

# View trace with timestamps
curl -v --trace-time https://api.example.com

Complete Debug Script

bash
#!/bin/bash
# API Debug Script

URL="https://api.example.com/users"
TOKEN="your_token_here"

echo "========== Request Info =========="
echo "URL: $URL"
echo "Time: $(date)"
echo ""

echo "========== Verbose Request Process =========="
curl -v -X GET "$URL" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     2>&1

echo ""
echo "========== Performance Metrics =========="
curl -w "DNS Lookup: %{time_namelookup}s\nTCP Connect: %{time_connect}s\nSSL Handshake: %{time_appconnect}s\nFirst Byte: %{time_starttransfer}s\nTotal Time: %{time_total}s\nHTTP Status: %{http_code}\n" \
     -o /dev/null -s "$URL" \
     -H "Authorization: Bearer $TOKEN"

echo ""
echo "========== Response Content =========="
curl -s "$URL" -H "Authorization: Bearer $TOKEN" | jq '.'

Common Issues Checklist

bash
# 1. Connection timeout
curl --connect-timeout 10 https://api.example.com

# 2. Read timeout
curl --max-time 30 https://api.example.com

# 3. DNS resolution issue
curl --resolve example.com:443:192.168.1.100 https://example.com

# 4. Certificate issue
curl --cacert /path/to/ca.crt https://api.example.com

# 5. Encoding issue
curl -H "Accept-Charset: UTF-8" https://api.example.com

# 6. Compressed transfer
curl --compressed https://api.example.com

Logging

bash
# Save complete debug log
curl -v https://api.example.com > response.txt 2>&1

# Save request and response separately
curl -v https://api.example.com \
     --trace-ascii request-trace.txt \
     -o response-body.txt

# Timestamped log
curl --trace-time -v https://api.example.com 2>&1 | tee debug.log

​