Troubleshooting
Connection Errors

Connection Errors

"Connection refused"

Symptom: NAT reports Connection refused when trying to reach the target API.

Solutions:

  1. Verify the API is running: curl -I https://api.example.com
  2. Check the URL — ensure there's no trailing path that's part of the endpoint, not the base URL
  3. Confirm the port is correct (HTTPS default: 443, HTTP default: 80)
  4. Check firewall rules on the API server

"Connection timed out"

Symptom: Requests time out after the default timeout period.

Solutions:

  1. Increase the timeout: nat scan --url ... --timeout 60
  2. Reduce concurrency to avoid overwhelming the server: --concurrency 2
  3. Check whether the API server is under load
  4. Verify network path — especially relevant if scanning across VPN or from CI runners

"SSL certificate verification failed"

Symptom: SSL: CERTIFICATE_VERIFY_FAILED or similar TLS error.

Common causes:

  • Self-signed certificate in staging environment
  • Certificate expired
  • Certificate hostname mismatch

Solutions:

  1. For staging with a self-signed cert (development only): 
    nat scan --url https://staging.example.com --no-tls-verify
    ⚠️

    Never use --no-tls-verify against production. This disables TLS verification and exposes your credentials to MITM attacks.

  2. For an internal CA: provide the CA bundle: 
    nat scan --url https://api.example.com --ca-bundle /path/to/internal-ca.pem
  3. For expired certificates: renew the certificate on the API server

"DNS resolution failed"

Symptom: NAT cannot resolve the API hostname.

Solutions:

  1. Check DNS from the machine running NAT: nslookup api.example.com
  2. If scanning from a CI runner, confirm the runner has access to your internal DNS
  3. Try using the IP address directly with a Host header override (not recommended for production)

"HTTP 502 / 503 / 504" responses

Symptom: NAT receives gateway or service unavailable errors.

Why this happens: These errors come from a load balancer or reverse proxy in front of your API, indicating the upstream service is unhealthy or overloaded.

Solutions:

  1. Check that the API service is healthy before scanning
  2. Reduce scan concurrency: --concurrency 2 --rate-limit 5
  3. Schedule scans during low-traffic periods

NAT can't reach the API from CI

Symptom: Scan works locally but fails in CI with connection errors.

Common causes and solutions:

CauseSolution
CI runner is on a different networkDeploy to a staging URL accessible from the CI runner's network
Firewall blocks CI runner IPsAllowlist your CI provider's IP ranges on the staging firewall
VPN requiredConfigure the CI workflow to connect to VPN before scanning
Staging isn't deployed yetTrigger the scan only after successful deployment

"Too many redirects"

Symptom: NAT follows redirects until hitting a limit.

Solutions:

  1. Check whether your --url points to the correct final URL (after all redirects)
  2. Provide the final URL directly to avoid redirect chains
  3. If HTTP-to-HTTPS redirect, use https:// in your --url

Rate limiting from the target API

Symptom: NAT receives 429 Too Many Requests during scanning.

Solutions:

  1. Add rate limiting: nat scan --url ... --rate-limit 5
  2. Reduce concurrency: --concurrency 2
  3. Add delays: --request-delay 500 (milliseconds between requests)
  4. Check if your staging API has stricter rate limits than production and adjust accordingly

Proxy support

If your environment requires an HTTP proxy to reach external APIs:

export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
nat scan --url https://api.example.com

NAT respects standard HTTP_PROXY and HTTPS_PROXY environment variables.

Next steps

Auth IssuesCI/CD Issues