Error Codes

The CyberSecFeed API uses standard HTTP status codes and custom error codes to indicate the success or failure of requests.

HTTP Status Codes

Status Code	Meaning
200	Success - Request completed successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Valid API key but insufficient permissions
404	Not Found - Requested resource does not exist
429	Too Many Requests - Monthly quota exceeded
500	Internal Server Error - Server-side error
503	Service Unavailable - Temporary service disruption

Error Response Format

All error responses follow this structure:

{
	"error": {
		"code": "ERROR_CODE",
		"message": "Human-readable error message",
		"details": {
			// Additional context about the error
		}
	},
	"meta": {
		"timestamp": "2024-01-25T12:00:00Z",
		"version": "v1",
		"correlationId": "req-12345"
	}
}

Common Error Codes

Authentication Errors

UNAUTHORIZED

• HTTP Status: 401
• Description: API key is missing or invalid
• Example:

{
	"error": {
		"code": "UNAUTHORIZED",
		"message": "Invalid or missing API key"
	}
}

API_KEY_EXPIRED

• HTTP Status: 401
• Description: API key has expired
• Example:

{
	"error": {
		"code": "API_KEY_EXPIRED",
		"message": "API key has expired. Please renew your subscription"
	}
}

Quota Errors

QUOTA_EXCEEDED

• HTTP Status: 429
• Description: Monthly API quota has been exceeded
• Example:

{
	"error": {
		"code": "QUOTA_EXCEEDED",
		"message": "Monthly API quota exceeded. Please upgrade your plan",
		"details": {
			"quota": 30000,
			"used": 30001,
			"resetDate": "2024-02-01T00:00:00Z"
		}
	}
}

Validation Errors

INVALID_PARAMETER

• HTTP Status: 400
• Description: One or more request parameters are invalid
• Example:

{
	"error": {
		"code": "INVALID_PARAMETER",
		"message": "Invalid parameter value",
		"details": {
			"parameter": "severity_min",
			"value": "11.0",
			"constraint": "Must be between 0.0 and 10.0"
		}
	}
}

MISSING_PARAMETER

• HTTP Status: 400
• Description: Required parameter is missing
• Example:

{
	"error": {
		"code": "MISSING_PARAMETER",
		"message": "Required parameter is missing",
		"details": {
			"parameter": "cve-id"
		}
	}
}

Resource Errors

CVE_NOT_FOUND

• HTTP Status: 404
• Description: Requested CVE does not exist
• Example:

{
	"error": {
		"code": "CVE_NOT_FOUND",
		"message": "CVE not found",
		"details": {
			"cveId": "CVE-9999-99999"
		}
	}
}

Server Errors

INTERNAL_ERROR

• HTTP Status: 500
• Description: Unexpected server error
• Example:

{
	"error": {
		"code": "INTERNAL_ERROR",
		"message": "An unexpected error occurred. Please try again later",
		"details": {
			"correlationId": "req-12345"
		}
	}
}

SERVICE_UNAVAILABLE

• HTTP Status: 503
• Description: Service is temporarily unavailable
• Example:

{
	"error": {
		"code": "SERVICE_UNAVAILABLE",
		"message": "Service temporarily unavailable. Please try again in a few minutes"
	}
}

Error Handling Best Practices

1. Always check the HTTP status code before parsing the response body
2. Log the correlationId for debugging and support requests
3. Implement exponential backoff for 503 errors
4. Monitor your quota usage to avoid 429 errors
5. Validate parameters locally before making API calls

Example Error Handling

import requests
import time

def make_api_request(url, headers):
    max_retries = 3
    retry_delay = 1

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

            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:
                error_data = response.json()
                print(f"Quota exceeded: {error_data['error']['message']}")
                # Handle quota exceeded - maybe notify user to upgrade
                break
            elif response.status_code == 503:
                if attempt < max_retries - 1:
                    time.sleep(retry_delay)
                    retry_delay *= 2  # Exponential backoff
                    continue
            else:
                error_data = response.json()
                print(f"Error: {error_data['error']['message']}")
                break

        except Exception as e:
            print(f"Request failed: {e}")

    return None