Troubleshooting Guide

This guide helps you diagnose and resolve common issues when using the CyberSecFeed API. If you can't find a solution here, please contact support at [email protected].

Common Error Codes

400 Bad Request

Meaning: Your request contains invalid parameters or is malformed.

Common Causes:

Invalid CVE ID format
Invalid date format (must be ISO 8601: YYYY-MM-DD)
Invalid parameter values (e.g., severity_min > 10)
Missing required parameters
Invalid include parameter values
Malformed field projection syntax

Solutions:

# ❌ Invalid CVE format
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cve/2024-0001"

# ✅ Correct CVE format
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001"

# ❌ Invalid date format
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cves?published_after=01/01/2024"

# ✅ Correct date format
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cves?published_after=2024-01-01"

# ❌ Invalid include parameter
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001?include=invalid"

# ✅ Valid include parameters
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001?include=acsc"

curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001?include=acsc,enrichment"

Debug Steps:

Check the error message in the response body
Validate all parameter formats
Ensure numeric values are within valid ranges
Remove optional parameters to isolate the issue

401 Unauthorized

Meaning: Authentication failed or API key is missing.

Common Causes:

Missing API key header
Invalid API key
Expired API key
Incorrect header name

Solutions:

# ❌ Missing API key
curl https://api.cybersecfeed.com/api/v1/ping

# ❌ Wrong header name
curl -H "API-Key: your-key" \
     https://api.cybersecfeed.com/api/v1/ping

# ❌ Wrong header format
curl -H "Authorization: Bearer your-key" \
     https://api.cybersecfeed.com/api/v1/ping

# ✅ Correct format
curl -H "X-API-Key: your-key" \
     https://api.cybersecfeed.com/api/v1/ping

Debug Steps:

Verify API key matches what was sent via email
Check for extra spaces or hidden characters
Ensure using correct environment (production)
Test with a simple endpoint like /ping

404 Not Found

Meaning: The requested resource doesn't exist.

Common Causes:

CVE ID doesn't exist in database
Incorrect endpoint URL
Typo in the path

Solutions:

# ❌ Wrong endpoint
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/vulnerabilities"

# ✅ Correct endpoint
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cves"

# Check if CVE exists before fetching details
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cves?ids=CVE-2024-99999"

Debug Steps:

Double-check the CVE ID format and existence
Verify the endpoint path matches documentation
Use the search endpoint to find similar CVEs
Check for typos in the URL

500 Internal Server Error

Meaning: Server-side error occurred.

Common Causes:

Temporary server issue
Unexpected input causing server error
Service maintenance

Solutions:

def handle_server_error(url, headers, max_retries=3):
    """Retry on server errors with exponential backoff"""

    wait_times = [1, 2, 4]  # Seconds

    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code >= 500:
            if attempt < max_retries - 1:
                wait_time = wait_times[attempt]
                print(f"Server error. Retrying in {wait_time} seconds...")
                time.sleep(wait_time)
            else:
                raise Exception(f"Server error persists: {response.status_code}")
        else:
            return response

Debug Steps:

Wait a few minutes and retry
Check the status page for incidents
Try a simpler request
Contact support if error persists

Connection Issues

SSL/TLS Errors

Symptoms:

SSL certificate verification failed
Connection refused
Handshake errors

Solutions:

# For testing only - NOT for production
import requests
from requests.packages.urllib3.exceptions import InsecureRequestWarning

# Suppress SSL warnings (testing only)
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

# Verify SSL certificates are valid
response = requests.get(
    "https://api.cybersecfeed.com/api/v1/ping",
    headers={"X-API-Key": "your-key"},
    verify=True  # Always True in production
)

Timeout Issues

Symptoms:

Requests hanging indefinitely
Connection timeout errors
Read timeout errors

Solutions:

import requests

# Set appropriate timeouts
response = requests.get(
    "https://api.cybersecfeed.com/api/v1/cves",
    headers={"X-API-Key": "your-key"},
    timeout=(5, 30)  # (connection timeout, read timeout)
)

# For large responses, increase read timeout
response = requests.get(
    "https://api.cybersecfeed.com/api/v1/cves?limit=100",
    headers={"X-API-Key": "your-key"},
    timeout=(5, 60)  # Longer read timeout
)

DNS Resolution

Symptoms:

"Failed to resolve host"
"Unknown host"
Intermittent connection failures

Debug Steps:

# Test DNS resolution
nslookup api.cybersecfeed.com
dig api.cybersecfeed.com

# Test connectivity
ping api.cybersecfeed.com
curl -I https://api.cybersecfeed.com

# Check with different DNS
dig @8.8.8.8 api.cybersecfeed.com

Performance Issues

Slow Response Times

Common Causes:

Not using connection pooling
Requesting unnecessary fields
Large result sets without pagination

Optimizations:

# 1. Use connection pooling
session = requests.Session()
adapter = requests.adapters.HTTPAdapter(
    pool_connections=10,
    pool_maxsize=10,
    max_retries=3
)
session.mount("https://", adapter)

# 2. Use field projection
response = session.get(
    "https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001",
    params={"fields": "id,cvss.baseScore,kev"}
)

# 3. Implement pagination properly
def get_all_results(session, base_url, params):
    all_results = []
    params["limit"] = 100  # Max per page

    while True:
        response = session.get(base_url, params=params)
        data = response.json()

        all_results.extend(data["data"]["cves"])

        if not data["data"]["pagination"].get("hasMore"):
            break

        params["after"] = data["data"]["pagination"]["nextCursor"]

    return all_results

High Memory Usage

Common Causes:

Loading too many results at once
Not streaming large responses
Memory leaks in long-running processes

Solutions:

# Process results in chunks
def process_cves_in_chunks(cve_ids, chunk_size=50):
    for i in range(0, len(cve_ids), chunk_size):
        chunk = cve_ids[i:i + chunk_size]

        # Process chunk
        response = session.get(
            "https://api.cybersecfeed.com/api/v1/cves",
            params={"ids": ",".join(chunk)}
        )

        # Process and release memory
        process_chunk(response.json())

        # Explicit cleanup if needed
        del response

Data Issues

Missing Enrichment Data

Symptoms:

No KEV data when expected
Missing EPSS scores
No ACSC advisories in response
Expected enrichment data not appearing

Common Causes:

ACSC data requires explicit inclusion: ACSC data is only returned when include=acsc parameter is used
Not all CVEs have KEV data (only ~0.5% are actively exploited)
EPSS scores may not be available for very new or old CVEs
ACSC advisories are regional and selective
Enrichment framework data requires include=enrichment parameter

Verification:

def check_enrichment_coverage(cve_id):
    """Check what enrichment data is available"""

    # Default request (includes KEV and EPSS when available)
    response = session.get(
        f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}"
    )
    cve_default = response.json()["data"]["cve"]

    # Request with ACSC data
    response_acsc = session.get(
        f"https://api.cybersecfeed.com/api/v1/cve/{cve_id}?include=acsc"
    )
    cve_with_acsc = response_acsc.json()["data"]["cve"]

    print(f"CVE: {cve_id}")
    print(f"Has KEV: {'Yes' if cve_default.get('kev') else 'No'}")
    print(f"Has EPSS: {'Yes' if cve_default.get('epss') else 'No'}")
    print(f"Has ACSC (with include=acsc): {'Yes' if cve_with_acsc.get('acsc') else 'No'}")
    print(f"ACSC in default response: {'Yes' if cve_default.get('acsc') else 'No (expected - requires include=acsc)'}")

    # Get stats for context
    stats = session.get(
        "https://api.cybersecfeed.com/api/v1/stats"
    ).json()

    print("\nPlatform Coverage:")
    print(f"Total CVEs: {stats['data']['stats']['totalCves']}")
    print(f"With KEV: {stats['data']['stats']['totalKev']}")
    print(f"With EPSS: {stats['data']['stats']['totalWithEpss']}")
    print(f"With ACSC: {stats['data']['stats']['totalWithAcsc']}")

ACSC Data Not Appearing

Symptoms:

Expected ACSC notices not in response
Inconsistent ACSC data between requests
Documentation shows ACSC but API doesn't return it

Common Causes:

Missing include=acsc parameter (most common)
ACSC data genuinely not available for this CVE
Confusing old documentation that showed ACSC by default

Solutions:

# ❌ This will NOT include ACSC data
curl -H "X-API-Key: your-key" \
     https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001

# ✅ This will include ACSC data if available
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001?include=acsc"

# ✅ Include both ACSC and enrichment data
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001?include=acsc,enrichment"

# ✅ Search with ACSC data included
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cves?severity_min=7.0&include=acsc&limit=10"

Inconsistent Results

Common Causes:

Using different include parameters between requests
Caching at different layers
Data updates between requests
Regional CDN differences

Solutions:

# Force cache bypass for testing
curl -H "X-API-Key: your-key" \
     -H "Cache-Control: no-cache" \
     "https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001?include=acsc"

# Check response headers for cache status
curl -I -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001?include=acsc"

# Ensure consistent parameters across requests
curl -H "X-API-Key: your-key" \
     "https://api.cybersecfeed.com/api/v1/cve/CVE-2024-0001?include=acsc&fields=id,cvss,acsc"

Debugging Tools

API Request Debugger

import requests
import json
from datetime import datetime

class APIDebugger:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.cybersecfeed.com/api/v1"

    def debug_request(self, endpoint, params=None):
        """Make request with detailed debugging info"""

        url = f"{self.base_url}{endpoint}"
        headers = {"X-API-Key": self.api_key}

        print(f"=== API Debug Info ===")
        print(f"Timestamp: {datetime.utcnow().isoformat()}")
        print(f"URL: {url}")
        print(f"Headers: {headers}")
        print(f"Params: {params}")

        # Check for common parameter issues
        if params:
            if 'include' in params:
                print(f"✓ Include parameter detected: {params['include']}")
            else:
                print("ℹ No include parameter - ACSC data will not be returned")
        print()

        try:
            response = requests.get(url, headers=headers, params=params)

            print(f"Status Code: {response.status_code}")
            print(f"Response Headers:")
            for key, value in response.headers.items():
                if key.lower() in ['etag', 'content-length', 'content-type']:
                    print(f"  {key}: {value}")

            print(f"\nResponse Time: {response.elapsed.total_seconds():.2f}s")

            if response.status_code != 200:
                print(f"\nError Response:")
                print(json.dumps(response.json(), indent=2))
            else:
                print(f"\nSuccess! Response size: {len(response.content)} bytes")

            return response

        except Exception as e:
            print(f"\nException occurred: {type(e).__name__}")
            print(f"Error: {str(e)}")
            raise

# Usage
debugger = APIDebugger("your-key")
debugger.debug_request("/cve/CVE-2024-0001")

Health Check Script

#!/bin/bash
# API health check script

API_KEY="your-key"
BASE_URL="https://api.cybersecfeed.com/api/v1"

echo "=== CyberSecFeed API Health Check ==="
echo "Time: $(date -u)"
echo

# 1. Basic connectivity
echo "1. Testing basic connectivity..."
if curl -s -f -o /dev/null -w "%{http_code}" "$BASE_URL/ping-lite" -H "X-API-Key: $API_KEY" | grep -q "200"; then
    echo "✅ Basic connectivity: OK"
else
    echo "❌ Basic connectivity: FAILED"
fi

# 2. Full health check
echo -e "\n2. Full health check..."
HEALTH_RESPONSE=$(curl -s -H "X-API-Key: $API_KEY" "$BASE_URL/ping")
if echo "$HEALTH_RESPONSE" | jq -e '.data.status == "ok"' > /dev/null; then
    echo "✅ Full health check: OK"
    echo "   Database connected: $(echo "$HEALTH_RESPONSE" | jq -r '.data.database.connected')"
else
    echo "❌ Full health check: FAILED"
fi

# 3. Sample API call
echo -e "\n3. Testing data retrieval..."
if curl -s -H "X-API-Key: $API_KEY" "$BASE_URL/stats" | jq -e '.data.stats' > /dev/null; then
    echo "✅ Data retrieval: OK"
else
    echo "❌ Data retrieval: FAILED"
fi

# 4. Test enrichment parameters
echo -e "\n4. Testing enrichment parameters..."
if curl -s -H "X-API-Key: $API_KEY" "$BASE_URL/cves?limit=1&include=acsc" | jq -e '.data.cves' > /dev/null; then
    echo "✅ ACSC parameter: OK"
else
    echo "❌ ACSC parameter: FAILED"
fi

echo -e "\n=== Health check complete ==="

Getting Help

Before Contacting Support

Check this guide for your specific error
Verify your API key is active and valid
Test with curl to rule out code issues
Check the status page for known incidents
Review recent changes to your integration

Information to Provide

When contacting support, include:

Request details:
- Exact URL and parameters
- Request headers (hide API key)
- Response status and body
Error context:
- When the error started
- Frequency of occurrence
- Any recent changes
Debug information:
- Correlation ID from response
- Timestamp of failed requests
- Your account email

Example Support Request

Subject: 500 Error on CVE Batch Endpoint

Account: [email protected]
Endpoint: GET /api/v1/cves
Parameters: ids=CVE-2024-0001,CVE-2024-0002
Error: 500 Internal Server Error
Correlation ID: req-abc123def456
Timestamp: 2024-01-25T14:30:00Z

The error occurs consistently when including CVE-2024-0002 in batch requests.
Individual requests to this CVE work fine. Started happening today at 14:00 UTC.

curl command to reproduce:
curl -H "X-API-Key: [REDACTED]" \
  "https://api.cybersecfeed.com/api/v1/cves?ids=CVE-2024-0001,CVE-2024-0002"

FAQ

Q: Why am I getting 401 errors with a valid API key? A: Check that you're using X-API-Key (with hyphens, not underscores) as the header name.

Q: Can I increase my monthly API quota? A: Yes, upgrade your plan at https://cybersecfeed.com/pricing for higher monthly quotas or contact [email protected] for custom enterprise quotas.

Q: Why am I not seeing ACSC data in my API responses? A: ACSC data requires the include=acsc parameter. It's not included by default for performance optimization. Add ?include=acsc to your requests.

Q: What's the difference between old and new API behavior? A: Previously, enrichment data like ACSC was included by default. Now it's parameter-controlled (include=acsc, include=enrichment) for better performance.

Q: Why don't all CVEs have EPSS scores? A: EPSS scores are calculated for CVEs with sufficient data. New or obscure CVEs may lack scores.

Q: How often is data updated? A: CVE data is updated in real-time. KEV updates hourly, EPSS updates daily, ACSC updates hourly.

Q: Can I cache API responses? A: Yes, use ETags for efficient caching. Respect cache headers in responses. Note that responses with different include parameters have different cache keys.

Q: Do I need to use include=acsc for every request? A: Only if you need ACSC data. For basic vulnerability information, the default request (without include parameters) is faster and includes KEV/EPSS when available.

Common Error Codes​

400 Bad Request​

401 Unauthorized​

404 Not Found​

500 Internal Server Error​

Connection Issues​

SSL/TLS Errors​

Timeout Issues​

DNS Resolution​

Performance Issues​

Slow Response Times​

High Memory Usage​

Data Issues​

Missing Enrichment Data​

ACSC Data Not Appearing​

Inconsistent Results​

Debugging Tools​

API Request Debugger​

Health Check Script​

Getting Help​

Before Contacting Support​

Information to Provide​

Example Support Request​

FAQ​

Common Error Codes

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Connection Issues

SSL/TLS Errors

Timeout Issues

DNS Resolution

Performance Issues

Slow Response Times

High Memory Usage

Data Issues

Missing Enrichment Data

ACSC Data Not Appearing

Inconsistent Results

Debugging Tools

API Request Debugger

Health Check Script

Getting Help

Before Contacting Support

Information to Provide

Example Support Request

FAQ