Browse cheat sheets · APIs

Technology: APIsCategory: HTTP & API TestingDifficulty: IntermediateUpdated

cURL Quick Reference

Use cURL to test and troubleshoot HTTP APIs with practical patterns for methods, headers, authentication, JSON bodies, files, redirects, timeouts, retries, response inspection, and safe production diagnostics.

On this page
  1. Problem
  2. Quick answer
  3. Code / commands
  4. 1. Simple GET request
  5. 2. Send an explicit HTTP method
  6. 3. Add an Accept header
  7. 4. Send JSON
  8. 5. Use --json for JSON requests
  9. 6. Send JSON from a file
  10. 7. Send raw request-body bytes from a file
  11. 8. Add a Bearer token
  12. 9. Basic authentication
  13. 10. API key in a header
  14. 11. API key in a query string
  15. 12. Add multiple headers
  16. 13. Send query parameters safely
  17. 14. Send form URL-encoded data
  18. 15. Send multipart form data
  19. 16. Upload a file directly
  20. 17. Download a file to a specific name
  21. 18. Preserve the server-provided filename
  22. 19. Follow redirects
  23. 20. Show response headers and body
  24. 21. Save response headers separately
  25. 22. Show only response headers
  26. 23. Print only the HTTP status code
  27. 24. Print status plus timing
  28. 25. Print DNS and TLS timing
  29. 26. Fail on HTTP errors while keeping useful output
  30. 27. Use script-friendly output
  31. 28. Set a connection timeout
  32. 29. Set an overall timeout
  33. 30. Retry transient failures
  34. 31. Be careful retrying POST/PATCH/DELETE
  35. 32. Use an idempotency key when the API supports it
  36. 33. Retry more broadly only when justified
  37. 34. Inspect verbose request/response details
  38. 35. Never paste verbose output publicly without reviewing it
  39. 36. Use trace output for deeper protocol debugging
  40. 37. Force HTTP/1.1 for comparison
  41. 38. Request HTTP/2 where supported
  42. 39. Inspect the negotiated HTTP version
  43. 40. Inspect remote IP
  44. 41. Override DNS for one request
  45. 42. Do not edit /etc/hosts just to test one endpoint
  46. 43. Set the Host header carefully
  47. 44. Use a proxy explicitly
  48. 45. Bypass proxy for selected hosts
  49. 46. Show request headers with -v, but avoid exposing tokens
  50. 47. Send cookies
  51. 48. Save response cookies
  52. 49. Send saved cookies later
  53. 50. Send a custom User-Agent
  54. 51. Add a correlation ID
  55. 52. Inspect rate-limit headers
  56. 53. Respect Retry-After
  57. 54. Send conditional GET requests with ETag
  58. 55. Send conditional requests by modification time
  59. 56. Download and resume a large file
  60. 57. Limit download rate for controlled testing
  61. 58. Send compressed-response support
  62. 59. Inspect content type
  63. 60. Detect HTML error pages from proxies or gateways
  64. 61. Write body and status separately in a shell script
  65. 62. Check cURL’s process exit code
  66. 63. HTTP 500 can still produce cURL exit code 0 without --fail
  67. 64. Use HEAD for metadata only when the server supports it
  68. 65. Test CORS preflight manually
  69. 66. Test an OPTIONS endpoint directly
  70. 67. Send PATCH JSON
  71. 68. Send DELETE
  72. 69. Avoid putting secrets directly in the command line
  73. 70. Use a config file for repeatable requests
  74. 71. Use .netrc only when its security model fits
  75. 72. Test TLS verification normally
  76. 73. Avoid -k / --insecure as a normal fix
  77. 74. Use a custom CA certificate when appropriate
  78. 75. Use a client certificate when mTLS is required
  79. 76. Debug hostname/TLS separately from HTTP behavior
  80. 77. Compare API behavior with and without redirects
  81. 78. Be careful sending credentials across redirects
  82. 79. Test response body size
  83. 80. Print a compact diagnostic line
  84. What the result means
  85. What to look for
  86. 401 Unauthorized
  87. 403 Forbidden
  88. 404 Not Found
  89. 429 Too Many Requests
  90. 5xx
  91. Long DNS time
  92. Fast connect but high TTFB
  93. TLS failure
  94. Production notes
  95. cURL is an excellent reproduction tool
  96. Protect secrets
  97. Retries must respect idempotency
  98. --insecure changes the security model
  99. Performance diagnosis needs several timings
  100. Shell syntax differs across environments
  101. Production state-changing calls deserve explicit intent
  102. Common mistakes
  103. 1. Confusing Accept and Content-Type
  104. 2. Testing HTTP success using only cURL exit code
  105. 3. Using -k to “fix” TLS
  106. 4. Printing tokens in verbose logs
  107. 5. Retrying POST requests blindly
  108. 6. Manually building query strings without encoding
  109. 7. Using --data for binary payloads
  110. 8. Assuming HEAD behaves exactly like GET
  111. 9. Ignoring redirects
  112. 10. Treating one timing sample as proof of performance
  113. Next step
  114. Related deep dives

Problem

You need to call or troubleshoot an HTTP API quickly from a terminal.

Typical engineering tasks include:

  • send GET, POST, PUT, PATCH, or DELETE requests
  • add headers and authentication
  • send JSON safely
  • upload or download files
  • inspect response headers and status codes
  • follow redirects
  • diagnose TLS, DNS, timeout, proxy, or connectivity problems
  • test retries without accidentally duplicating unsafe requests
  • reproduce an API issue outside the application

The goal is to make the request explicit, observable, and safe enough to use during real production troubleshooting.

Quick answer

Basic JSON API request:

curl \
  --request GET \
  --url "https://api.example.com/v1/reports/123" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $API_TOKEN"

POST JSON:

curl \
  --request POST \
  --url "https://api.example.com/v1/reports" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{
    "reportType": "sales",
    "startDate": "2026-10-01",
    "endDate": "2026-10-31"
  }'

For troubleshooting, start with:

curl \
  --silent \
  --show-error \
  --location \
  --dump-header headers.txt \
  --output body.json \
  --write-out "%{http_code}\n" \
  "https://api.example.com/health"

Code / commands

1. Simple GET request

curl "https://api.example.com/v1/status"

Use when the endpoint does not require headers or authentication.


2. Send an explicit HTTP method

curl \
  --request PATCH \
  "https://api.example.com/v1/users/123"

Use --request when the method is not implied by another option.

For many common cases:

  • --data implies POST unless another method is specified
  • --head performs a HEAD-style request
  • --upload-file commonly uses PUT semantics unless overridden

Being explicit improves readability in reusable examples.


3. Add an Accept header

curl \
  --header "Accept: application/json" \
  "https://api.example.com/v1/users/123"

Accept tells the server which response format the client prefers.


4. Send JSON

curl \
  --request POST \
  --url "https://api.example.com/v1/users" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Javi",
    "active": true
  }'

Content-Type describes the request body.

Do not confuse it with Accept.


5. Use --json for JSON requests

On modern cURL versions:

curl \
  --json '{
    "name": "Javi",
    "active": true
  }' \
  "https://api.example.com/v1/users"

--json is shorthand that sends JSON and sets the relevant JSON headers.

If you support older environments, use explicit Content-Type + --data instead.


6. Send JSON from a file

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://api.example.com/v1/reports"

This is safer and easier to maintain for large request bodies.


7. Send raw request-body bytes from a file

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --data-binary @payload.json \
  "https://api.example.com/v1/reports"

Use --data-binary when the payload must be sent without cURL’s form-style processing behavior.


8. Add a Bearer token

curl \
  --header "Authorization: Bearer $API_TOKEN" \
  "https://api.example.com/v1/profile"

Prefer environment variables over putting secrets directly into shell history.


9. Basic authentication

curl \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.example.com/v1/admin"

Do not hardcode credentials into scripts committed to source control.


10. API key in a header

curl \
  --header "X-API-Key: $API_KEY" \
  "https://api.example.com/v1/data"

Header name varies by API.

Use the provider’s documented authentication scheme.


11. API key in a query string

curl \
  "https://api.example.com/v1/data?api_key=$API_KEY"

Avoid this pattern unless required.

Query-string secrets can leak into:

  • logs
  • browser history
  • proxies
  • monitoring systems

Headers are generally safer for credentials.


12. Add multiple headers

curl \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Correlation-ID: test-123" \
  "https://api.example.com/v1/orders"

Correlation IDs are useful when matching the client request to server logs.


13. Send query parameters safely

curl \
  --get \
  --url "https://api.example.com/v1/reports" \
  --data-urlencode "merchant=ACME & Sons" \
  --data-urlencode "startDate=2026-10-01"

--data-urlencode avoids manual encoding mistakes.


14. Send form URL-encoded data

curl \
  --request POST \
  --data-urlencode "username=javi" \
  --data-urlencode "scope=reports read" \
  "https://auth.example.com/token"

This sends:

application/x-www-form-urlencoded

which is common in OAuth/token flows.


15. Send multipart form data

curl \
  --form "description=monthly report" \
  --form "file=@report.csv" \
  "https://api.example.com/v1/uploads"

Use --form for multipart uploads.


16. Upload a file directly

curl \
  --upload-file report.csv \
  "https://storage.example.com/files/report.csv"

Use when the endpoint expects the request body to be the file itself.

Check the API’s expected method and authentication model.


17. Download a file to a specific name

curl \
  --output report.csv \
  "https://api.example.com/v1/reports/123/download"

18. Preserve the server-provided filename

curl \
  --remote-name \
  "https://example.com/files/report.csv"

Use only when you trust the source and destination directory.


19. Follow redirects

curl \
  --location \
  "https://example.com/download"

Without --location, cURL normally reports the redirect response instead of following it.


20. Show response headers and body

curl \
  --include \
  "https://api.example.com/v1/status"

--include puts response headers before the body in the same output stream.

Useful interactively, less convenient for automation.


21. Save response headers separately

curl \
  --dump-header headers.txt \
  --output body.json \
  "https://api.example.com/v1/status"

Use this when headers and body need separate inspection.


22. Show only response headers

curl \
  --head \
  "https://example.com/resource"

This asks for a HEAD request.

Be aware that not every API implements HEAD meaningfully.


23. Print only the HTTP status code

curl \
  --silent \
  --output /dev/null \
  --write-out "%{http_code}\n" \
  "https://api.example.com/health"

On Windows PowerShell, /dev/null is not native. Use an environment-appropriate null target or save the response to a file.


24. Print status plus timing

curl \
  --silent \
  --output /dev/null \
  --write-out \
  "status=%{http_code} total=%{time_total}s connect=%{time_connect}s ttfb=%{time_starttransfer}s\n" \
  "https://api.example.com/health"

Useful for separating:

  • connect time
  • server/TTFB delay
  • total transfer time

Do not treat one sample as a performance benchmark.


25. Print DNS and TLS timing

curl \
  --silent \
  --output /dev/null \
  --write-out \
  "dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s\n" \
  "https://api.example.com/health"

Use when distinguishing:

  • DNS delay
  • TCP connection delay
  • TLS handshake delay
  • application/server delay

26. Fail on HTTP errors while keeping useful output

curl \
  --fail-with-body \
  --show-error \
  "https://api.example.com/v1/resource"

--fail-with-body returns a failure exit code for HTTP error responses while preserving the response body.

This is generally more useful for scripts than plain --fail.

Check cURL version if unavailable in older environments.


27. Use script-friendly output

curl \
  --silent \
  --show-error \
  --fail-with-body \
  "https://api.example.com/v1/resource"

This combination means:

  • --silent: suppress progress meter
  • --show-error: still print cURL errors
  • --fail-with-body: non-zero on HTTP errors, keep body

28. Set a connection timeout

curl \
  --connect-timeout 5 \
  "https://api.example.com/health"

This limits how long cURL waits to establish the connection.


29. Set an overall timeout

curl \
  --max-time 30 \
  "https://api.example.com/v1/reports/123"

This limits the full request duration.

Use values aligned with the API’s real latency expectations.


30. Retry transient failures

curl \
  --retry 3 \
  --retry-delay 2 \
  --retry-max-time 30 \
  "https://api.example.com/health"

Use retries mainly for operations that are safe to repeat.


31. Be careful retrying POST/PATCH/DELETE

A retry can duplicate side effects if the API is not idempotent.

For write operations, prefer:

  • API-supported idempotency keys
  • server-side request IDs
  • safe retry contracts

Do not blindly retry state-changing calls.


32. Use an idempotency key when the API supports it

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REQUEST_ID" \
  --data @payload.json \
  "https://api.example.com/v1/payments"

The header name and behavior are API-specific.

Do not invent an idempotency mechanism the server does not support.


33. Retry more broadly only when justified

Modern cURL supports:

curl \
  --retry 3 \
  --retry-all-errors \
  "https://api.example.com/health"

This broadens which failures are retried.

Use cautiously, especially for state-changing requests.


34. Inspect verbose request/response details

curl \
  --verbose \
  "https://api.example.com/v1/status"

Useful for:

  • request headers
  • response headers
  • redirects
  • TLS negotiation
  • proxy behavior
  • connection reuse

Be careful: verbose output can expose credentials.


35. Never paste verbose output publicly without reviewing it

Verbose traces may include:

Authorization headers
cookies
API keys
internal hostnames
session tokens

Redact secrets before sharing logs or tickets.


36. Use trace output for deeper protocol debugging

curl \
  --trace-ascii trace.txt \
  "https://api.example.com/v1/status"

Use only when necessary.

Trace files can contain sensitive headers and bodies.

Treat them as secrets until reviewed.


37. Force HTTP/1.1 for comparison

curl \
  --http1.1 \
  "https://api.example.com/v1/status"

Use when investigating protocol-specific behavior.


38. Request HTTP/2 where supported

curl \
  --http2 \
  "https://api.example.com/v1/status"

Actual support depends on how cURL was built and what the server negotiates.


39. Inspect the negotiated HTTP version

curl \
  --silent \
  --output /dev/null \
  --write-out "%{http_version}\n" \
  "https://api.example.com/v1/status"

Useful when debugging HTTP/1.1 vs HTTP/2 differences.


40. Inspect remote IP

curl \
  --silent \
  --output /dev/null \
  --write-out "%{remote_ip}\n" \
  "https://api.example.com/health"

Useful when diagnosing DNS, load balancers, or regional routing.


41. Override DNS for one request

curl \
  --resolve api.example.com:443:203.0.113.10 \
  "https://api.example.com/health"

This keeps the original hostname for:

  • TLS SNI
  • Host header

while connecting to the specified IP.

Use for controlled troubleshooting only.


42. Do not edit /etc/hosts just to test one endpoint

--resolve is often safer because it affects only that cURL invocation.


43. Set the Host header carefully

curl \
  --header "Host: api.example.com" \
  "https://203.0.113.10/health"

This does not fully replace hostname-based TLS behavior.

For HTTPS testing against a specific IP, --resolve is usually better.


44. Use a proxy explicitly

curl \
  --proxy "http://proxy.example.com:8080" \
  "https://api.example.com/health"

Useful when testing whether application failures are proxy-related.


45. Bypass proxy for selected hosts

curl \
  --noproxy "api.example.com" \
  "https://api.example.com/health"

Check environment variables such as:

HTTP_PROXY
HTTPS_PROXY
NO_PROXY

when cURL behaves differently across machines.


46. Show request headers with -v, but avoid exposing tokens

For authenticated calls, consider temporarily testing against a non-sensitive endpoint or redacting logs.

Do not send real production tokens to public paste sites.


47. Send cookies

curl \
  --cookie "session_id=$SESSION_ID" \
  "https://api.example.com/profile"

Use only when the API intentionally uses cookie-based authentication/session state.


48. Save response cookies

curl \
  --cookie-jar cookies.txt \
  "https://api.example.com/login"

49. Send saved cookies later

curl \
  --cookie cookies.txt \
  "https://api.example.com/profile"

Protect cookie files like credentials.


50. Send a custom User-Agent

curl \
  --user-agent "javi-builds-api-test/1.0" \
  "https://api.example.com/health"

Useful when server logs or rate limits distinguish clients.


51. Add a correlation ID

REQUEST_ID="$(uuidgen)"

curl \
  --header "X-Correlation-ID: $REQUEST_ID" \
  "https://api.example.com/v1/reports"

Exact header naming depends on the API.

Use a stable request identifier when correlating client and server logs.


52. Inspect rate-limit headers

curl \
  --include \
  "https://api.example.com/v1/data"

Look for API-specific headers such as:

RateLimit-*
X-RateLimit-*
Retry-After

Header names vary by implementation.


53. Respect Retry-After

If the server returns:

429 Too Many Requests

and a Retry-After header, use that guidance instead of hammering the endpoint.


54. Send conditional GET requests with ETag

First inspect:

curl \
  --include \
  "https://api.example.com/v1/config"

If response includes:

ETag: "abc123"

then:

curl \
  --header 'If-None-Match: "abc123"' \
  "https://api.example.com/v1/config"

A 304 Not Modified can avoid downloading unchanged content.


55. Send conditional requests by modification time

curl \
  --header "If-Modified-Since: Wed, 01 Oct 2026 12:00:00 GMT" \
  "https://api.example.com/v1/config"

Use only when the server supports meaningful last-modified semantics.


56. Download and resume a large file

curl \
  --continue-at - \
  --output large-file.zip \
  "https://example.com/large-file.zip"

Resume support depends on server range-request behavior.


57. Limit download rate for controlled testing

curl \
  --limit-rate 1M \
  --output file.bin \
  "https://example.com/file.bin"

Useful for simulating constrained clients.


58. Send compressed-response support

curl \
  --compressed \
  "https://api.example.com/v1/data"

This asks the server for supported compressed encodings and automatically decompresses the response.


59. Inspect content type

curl \
  --silent \
  --output /dev/null \
  --write-out "%{content_type}\n" \
  "https://api.example.com/v1/data"

Useful when an endpoint unexpectedly returns HTML instead of JSON.


60. Detect HTML error pages from proxies or gateways

If your client expects JSON but receives an HTML body, inspect:

curl \
  --include \
  "https://api.example.com/v1/data"

Look at:

  • status code
  • Content-Type
  • Server
  • gateway/proxy headers

The failure may be upstream of the application.


61. Write body and status separately in a shell script

status="$(
  curl \
    --silent \
    --show-error \
    --output response.json \
    --write-out "%{http_code}" \
    "https://api.example.com/v1/data"
)"

echo "HTTP $status"

This keeps machine-readable body and status separate.


62. Check cURL’s process exit code

curl \
  --fail-with-body \
  --silent \
  --show-error \
  "https://api.example.com/v1/data"

echo $?

On POSIX shells:

0
→ cURL considered the request successful

non-zero
→ transport/protocol failure or HTTP failure with --fail*

Do not confuse cURL exit code with HTTP status code.


63. HTTP 500 can still produce cURL exit code 0 without --fail

By default, cURL can successfully transfer a 500 response.

If scripts should fail on HTTP errors, use:

--fail-with-body

and inspect the HTTP status too.


64. Use HEAD for metadata only when the server supports it

curl --head "https://example.com/file.zip"

Useful for:

  • content length
  • ETag
  • last modified
  • redirects

Some APIs do not implement HEAD consistently.


65. Test CORS preflight manually

curl \
  --request OPTIONS \
  --header "Origin: https://app.example.com" \
  --header "Access-Control-Request-Method: POST" \
  --header "Access-Control-Request-Headers: authorization,content-type" \
  "https://api.example.com/v1/reports"

Inspect response headers such as:

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers

CORS is enforced by browsers, not by cURL itself.


66. Test an OPTIONS endpoint directly

curl \
  --request OPTIONS \
  --include \
  "https://api.example.com/v1/reports"

Do not assume every API exposes useful method metadata through OPTIONS.


67. Send PATCH JSON

curl \
  --request PATCH \
  --header "Content-Type: application/json" \
  --data '{
    "status": "disabled"
  }' \
  "https://api.example.com/v1/users/123"

Be careful with production state-changing endpoints.


68. Send DELETE

curl \
  --request DELETE \
  --header "Authorization: Bearer $API_TOKEN" \
  "https://api.example.com/v1/users/123"

DELETE may be destructive.

Test against non-production or a known disposable resource unless the change is explicitly intended.


69. Avoid putting secrets directly in the command line

Risky:

curl \
  --header "Authorization: Bearer real-secret-token" \
  ...

Command lines may be retained in shell history or visible to local process inspection.

Prefer environment variables or secure secret tooling.


70. Use a config file for repeatable requests

Example curl.conf:

silent
show-error
fail-with-body
header = "Accept: application/json"

Then:

curl --config curl.conf "https://api.example.com/v1/data"

Do not store secrets in a committed config file.


71. Use .netrc only when its security model fits

cURL can use credentials from .netrc.

If you use it:

  • restrict file permissions
  • do not commit it
  • understand which hosts it applies to

For many production workflows, dedicated secret management is preferable.


72. Test TLS verification normally

curl "https://api.example.com/health"

Do not disable certificate verification by default.


73. Avoid -k / --insecure as a normal fix

curl --insecure "https://api.example.com/health"

This disables TLS certificate verification.

Use only for controlled diagnostics when you understand the risk.

Do not normalize it in production scripts.


74. Use a custom CA certificate when appropriate

curl \
  --cacert company-root-ca.pem \
  "https://internal-api.example.com/health"

This preserves TLS verification while trusting the intended internal CA.


75. Use a client certificate when mTLS is required

curl \
  --cert client-cert.pem \
  --key client-key.pem \
  "https://mtls.example.com/v1/data"

Protect private keys and certificate material.

Exact formats/options depend on your cURL build and certificate packaging.


76. Debug hostname/TLS separately from HTTP behavior

Useful progression:

DNS resolve
→ TCP connect
→ TLS handshake
→ HTTP status
→ application body

Use timing, --verbose, and --resolve selectively to isolate the failing layer.


77. Compare API behavior with and without redirects

Without following:

curl \
  --include \
  "https://example.com/api"

Following redirects:

curl \
  --location \
  --include \
  "https://example.com/api"

This can reveal authentication or routing issues hidden behind a redirect.


78. Be careful sending credentials across redirects

When redirects cross hosts, understand how authentication headers/cookies are handled.

Do not force credential forwarding to unrelated hosts.

Review redirect targets first.


79. Test response body size

curl \
  --silent \
  --output /dev/null \
  --write-out "%{size_download}\n" \
  "https://api.example.com/v1/report"

Useful when a previously small API response becomes unexpectedly large.


80. Print a compact diagnostic line

curl \
  --silent \
  --show-error \
  --output response.out \
  --write-out \
  "status=%{http_code} ip=%{remote_ip} dns=%{time_namelookup}s connect=%{time_connect}s ttfb=%{time_starttransfer}s total=%{time_total}s bytes=%{size_download}\n" \
  "https://api.example.com/v1/data"

This is useful in incident notes because it captures both network and HTTP context.

What the result means

Signal What it helps identify
HTTP status Application/gateway outcome
cURL exit code Client/transport/protocol success or failure
time_namelookup DNS lookup time
time_connect Time until TCP connection established
time_appconnect Time until TLS handshake completed
time_starttransfer Time until first response byte
time_total Full request duration
remote_ip Actual server/load-balancer IP reached
content_type Response representation returned
size_download Response body size
Response headers Caching, rate limit, auth, gateway, tracing clues

A useful mental model is:

cURL exit code
→ did the client operation succeed?

HTTP status
→ what did the HTTP server say?

response body
→ what did the application/gateway explain?

What to look for

401 Unauthorized

Check:

  • missing/expired token
  • wrong auth scheme
  • wrong audience/scope
  • clock issues for signed tokens

Do not immediately regenerate credentials without first confirming which credential the request actually sent.

403 Forbidden

Authentication may have succeeded but authorization failed.

Check:

  • permissions
  • role/scope
  • resource policy
  • IP/network restrictions

404 Not Found

Check:

  • URL path
  • API version
  • tenant/resource ID
  • gateway routing
  • whether the service intentionally hides unauthorized resources as 404

429 Too Many Requests

Check:

  • Retry-After
  • rate-limit headers
  • request concurrency
  • client retry loops

Do not retry aggressively.

5xx

Check whether the response came from:

  • application
  • API gateway
  • reverse proxy
  • load balancer

Headers and body often reveal which layer failed.

Long DNS time

Investigate resolver/network path.

Fast connect but high TTFB

Likely server/application/gateway processing delay rather than initial network setup.

TLS failure

Check:

  • hostname
  • certificate chain
  • trust store
  • client certificate requirements
  • system clock

Avoid normalizing --insecure.

Production notes

cURL is an excellent reproduction tool

A minimal cURL request can separate:

client application bug
from
API/network/server behavior

Capture the smallest request that still reproduces the issue.

Protect secrets

Commands, verbose traces, shell history, CI logs, and ticket attachments can expose:

  • Bearer tokens
  • API keys
  • Basic auth
  • cookies
  • client certificates

Redact before sharing.

Retries must respect idempotency

A GET is usually safe to retry.

A POST may create duplicate state unless the API explicitly provides idempotency semantics.

--insecure changes the security model

It is a diagnostic tool, not a production fix.

If a private CA is expected, configure the CA trust correctly instead.

Performance diagnosis needs several timings

A slow time_total alone does not tell you whether the problem is:

  • DNS
  • network
  • TLS
  • server processing
  • download size

Use the timing fields together.

Shell syntax differs across environments

Line continuation differs between:

  • Bash/zsh: \
  • PowerShell: backtick or splatting/arrays
  • Windows cmd.exe: ^

The cURL options are the same, but quoting rules differ.

Production state-changing calls deserve explicit intent

Before running POST/PATCH/DELETE against production, confirm:

  • endpoint
  • resource ID
  • environment
  • authentication identity
  • payload
  • expected side effect

Common mistakes

1. Confusing Accept and Content-Type

Accept describes the desired response.

Content-Type describes the request body.

2. Testing HTTP success using only cURL exit code

A 500 can still be a successful transfer unless --fail* is used.

3. Using -k to “fix” TLS

This hides certificate problems rather than solving them.

4. Printing tokens in verbose logs

Redact secrets before sharing output.

5. Retrying POST requests blindly

This can duplicate side effects.

6. Manually building query strings without encoding

Use --data-urlencode.

7. Using --data for binary payloads

Use --data-binary or --upload-file when raw bytes matter.

8. Assuming HEAD behaves exactly like GET

Some services implement HEAD differently or not at all.

9. Ignoring redirects

A redirect can explain unexpected auth, gateway, or routing behavior.

10. Treating one timing sample as proof of performance

Repeat controlled tests and compare with server-side telemetry.

Next step

Use the observed failure to choose the next investigation.

  • 401/403 → inspect authentication and authorization.
  • 404 → verify route, version, resource identifier, and gateway routing.
  • 429 → inspect rate-limit headers and client retry/concurrency behavior.
  • 5xx → determine whether the application or gateway produced the error.
  • DNS slow → investigate resolver/network path.
  • TLS fails → verify hostname, certificate chain, trust, and mTLS requirements.
  • TTFB is high → inspect server-side execution and dependencies.
  • Download is slow but TTFB is fine → inspect response size/network throughput.
  • Client app fails but cURL succeeds → compare headers, auth, body, proxy, TLS, and redirect behavior.
  • Need systematic API debugging → move to Troubleshoot API Requests.

← All cheat sheets