https://docs.rs/veracode-platform

Veracode Platform Client Library

A comprehensive Rust client library for the Veracode security platform, providing type-safe and ergonomic access to Applications, Identity, Pipeline Scan, Sandbox, Policy, and Build APIs.

✨ Features

• 🔐 HMAC Authentication - Built-in Veracode API credential support with automatic signature generation
• 🛡️ Secure Credential Handling - All API credentials are securely wrapped to prevent accidental exposure in logs
• 🌍 Multi-Regional Support - Automatic endpoint routing for Commercial, European, and Federal regions
• 🔄 Smart API Routing - Automatically uses REST or XML APIs based on operation requirements
• 📱 Applications API - Complete application lifecycle management via REST API
• 👥 Identity API - User and team management via REST API
• 🔍 Pipeline Scan API - CI/CD security scanning via REST API
• 🧪 Sandbox API - Development sandbox management via REST API
• 🔨 Build API - Build management and SAST operations via XML API
• 📊 Scan API - File upload and scan operations via XML API
• 📋 Policy API - Security policy management and compliance evaluation with intelligent REST/XML API fallback
• 🚀 Async/Await - Built on tokio for high-performance concurrent operations
• ⚡ Type-Safe - Full Rust type safety with comprehensive serde serialization
• 📊 Rich Data Types - Comprehensive data structures for all API responses
• 🔧 Workflow Helpers - High-level operations combining multiple API calls
• 🔄 Intelligent Retry Logic - Automatic retry with exponential backoff for transient failures and smart rate limit handling
• 🔀 API Fallback System - Automatic fallback from REST API to XML API on permission errors for maximum compatibility
• ⏱️ Configurable Timeouts - Customizable connection and request timeouts for different use cases
• ⚡ Performance Optimized - Advanced memory allocation optimizations for high-throughput applications
• 🔒 Debug Safety - All sensitive credentials show [REDACTED] in debug output
• 🧪 Comprehensive Testing - Extensive test coverage including security measures

🚀 Quick Start

Add to your Cargo.toml:

[dependencies]
veracode-platform = "0.5.3"
tokio = { version = "1.0", features = ["full"] }

Basic Usage

use veracode_platform::{VeracodeConfig, VeracodeClient, RetryConfig, VeracodeRegion};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure client for your region with custom timeouts
    let config = VeracodeConfig::new(
        std::env::var("VERACODE_API_ID")?,
        std::env::var("VERACODE_API_KEY")?,
    )
    .with_region(VeracodeRegion::Commercial)  // Commercial (default), European, or Federal
    .with_timeouts(60, 600);                  // Optional: 60s connect, 10min request timeout
    
    // Create client
    let client = VeracodeClient::new(config)?;
    
    // Use Applications API (REST)
    let apps = client.get_all_applications().await?;
    println!("Found {} applications", apps.len());
    
    // Use Pipeline Scan API (REST)
    let pipeline = client.pipeline_api();
    // ... pipeline operations
    
    // Use Scan API for file uploads (XML)
    let scan_api = client.scan_api();
    // ... scan operations
    
    Ok(())
}

🌍 Regional Support

The library automatically handles regional endpoints for both REST and XML APIs:

use veracode_platform::{VeracodeConfig, VeracodeRegion};

// Commercial region (default)
let config = VeracodeConfig::new("api_id".to_string(), "api_key".to_string())
    .with_region(VeracodeRegion::Commercial);
// REST: api.veracode.com | XML: analysiscenter.veracode.com

// European region
let config = VeracodeConfig::new("api_id".to_string(), "api_key".to_string())
    .with_region(VeracodeRegion::European);
// REST: api.veracode.eu | XML: analysiscenter.veracode.eu

// US Federal region
let config = VeracodeConfig::new("api_id".to_string(), "api_key".to_string())
    .with_region(VeracodeRegion::Federal);
// REST: api.veracode.us | XML: analysiscenter.veracode.us

📚 API Modules

Applications API (REST)

Complete application lifecycle management:

use veracode_platform::app::{BusinessCriticality, CreateApplicationRequest};
// List all applications
let apps = client.get_all_applications().await?;

// Get specific application
let app_query = ApplicationQuery {
    name: Some("MyApp".to_string()),
    ..Default::default()
};
let app = client.get_application(app_query).await?;

// Create new application
let create_request = CreateApplicationRequest {
    name: "New App".to_string(),
    description: Some("My new application".to_string()),
    business_unit_id: Some(12345),
    teams: vec![],
    tags: vec![],
};
let new_app = client.create_application(create_request).await?;

// Create application with team assignment (new in 0.5.1)
// Teams are automatically resolved from names to GUIDs
let app_with_teams = client.create_application_if_not_exists(
    "My Team App",
    BusinessCriticality::High,
    Some("App with team assignment".to_string()),
    Some(vec!["Security Team".to_string(), "Development Team".to_string()])
).await?;

Pipeline Scan API (REST)

CI/CD security scanning:

use veracode_platform::pipeline::{CreateScanRequest, DevStage};

let pipeline = client.pipeline_api();

// Create a pipeline scan
let scan_request = CreateScanRequest {
    binary_name: "my-app.jar".to_string(),
    binary_size: file_data.len() as u64,
    binary_hash: calculate_sha256(&file_data),
    project_name: "My Project".to_string(),
    project_uri: Some("https://github.com/user/repo".to_string()),
    dev_stage: DevStage::Development,
    app_id: None,
    project_ref: Some("main".to_string()),
    scan_timeout: Some(30),
    plugin_version: None,
    emit_stack_dump: None,
    include_modules: None,
};

let scan_result = pipeline.create_scan(scan_request).await?;
println!("Created scan: {}", scan_result.scan_id);

// Monitor scan status
let scan_info = pipeline.get_scan(&scan_result.scan_id).await?;
println!("Scan status: {:?}", scan_info.status);

// Get findings when complete
if scan_info.status == ScanStatus::Complete {
    let findings = pipeline.get_findings(&scan_result.scan_id).await?;
    println!("Found {} security issues", findings.len());
}

Identity API (REST)

User and team management:

let identity = client.identity_api();

// List users
let users = identity.get_users(None).await?;

// Create new user
let create_user = CreateUserRequest {
    email: "user@example.com".to_string(),
    first_name: "John".to_string(),
    last_name: "Doe".to_string(),
    user_type: UserType::User,
    roles: vec![],
    teams: vec![],
};
let new_user = identity.create_user(create_user).await?;

// Manage teams
let teams = identity.get_teams().await?;

// Find team by name (new in 0.5.1)
let security_team = identity.get_team_by_name("Security Team").await?;

// Get team GUID for application creation (new in 0.5.1)
let team_guid = identity.get_team_guid_by_name("Security Team").await?;

Sandbox API (REST)

Development sandbox management:

let sandbox_api = client.sandbox_api();

// List sandboxes for an application
let sandboxes = sandbox_api.get_sandboxes("app-guid").await?;

// Create new sandbox
let create_request = CreateSandboxRequest {
    name: "Development Sandbox".to_string(),
    auto_recreate: Some(false),
    custom_fields: vec![],
};
let sandbox = sandbox_api.create_sandbox("app-guid", create_request).await?;

Scan API (XML)

File upload and scan operations:

let scan_api = client.scan_api();

// Upload file for scanning
let upload_request = UploadFileRequest {
    app_id: "12345".to_string(),
    file_path: "/path/to/file.jar".to_string(),
    sandbox_id: Some("sandbox-guid".to_string()),
};

let uploaded_file = scan_api.upload_file(upload_request).await?;
println!("Uploaded: {}", uploaded_file.file_name);

// Start pre-scan
let pre_scan = scan_api.begin_pre_scan(BeginPreScanRequest {
    app_id: "12345".to_string(),
    sandbox_id: Some("sandbox-guid".to_string()),
    scan_all_nonfatal_top_level_modules: Some(true),
    auto_scan: Some(true),
});

Policy API (REST + XML Fallback)

Security policy and compliance management with intelligent API fallback:

let policy_api = client.policy_api();

// Get organizational policies
let policies = policy_api.get_policies().await?;

// Evaluate policy compliance with automatic fallback
let (summary_report_opt, compliance_status, api_source) = policy_api
    .get_policy_status_with_fallback(
        &app_guid,          // Application GUID (for REST API)
        &app_id,           // Application ID (for XML API fallback)
        Some(&build_id),   // Build ID
        sandbox_guid.as_deref(), // Optional sandbox GUID
        sandbox_id.as_deref(),   // Optional sandbox ID (for fallback)
        30,                // Max retries
        10,                // Retry delay seconds
        true,              // Enable break build evaluation
        false,             // Don't force buildinfo API
    )
    .await?;

use veracode_platform::ApiSource;
match api_source {
    ApiSource::SummaryReport => {
        println!("✅ Used summary report API successfully");
        if let Some(report) = summary_report_opt {
            println!("Full summary report available");
        }
    },
    ApiSource::BuildInfo => {
        println!("🔄 Used getbuildinfo.do API (fallback)");
        println!("Policy status only - no full summary report");
    }
}
println!("Policy compliance status: {}", compliance_status);

// Force buildinfo API usage (for restricted permissions)
let (_, status, _) = policy_api
    .get_policy_status_with_fallback(
        &app_guid, &app_id, Some(&build_id), 
        None, None, 30, 10, true, 
        true  // Force buildinfo API
    )
    .await?;

// Check if build should break
use veracode_platform::PolicyApi;
if PolicyApi::should_break_build(&compliance_status) {
    let exit_code = PolicyApi::get_exit_code_for_status(&compliance_status);
    println!("❌ Build should break - exit code: {}", exit_code);
}

Build API (XML)

Build management and SAST operations:

let build_api = client.build_api();

// Get build list for application
let builds = build_api.get_build_list(GetBuildListRequest {
    app_id: "12345".to_string(),
    sandbox_id: None,
}).await?;

// Create new build
let create_build = CreateBuildRequest {
    app_id: "12345".to_string(),
    version: "1.0.0".to_string(),
    sandbox_id: None,
    lifecycle_stage: None,
    launch_date: None,
};
let build = build_api.create_build(create_build).await?;

Workflow Helpers

High-level operations combining multiple API calls:

let workflow = client.workflow();

// Complete application workflow
let workflow_config = WorkflowConfig {
    app_name: "My Application".to_string(),
    build_version: "1.0.0".to_string(),
    file_paths: vec!["/path/to/app.jar".to_string()],
    scan_timeout: Some(45),
    delete_incomplete_scans: true,
};

let result = workflow.run_complete_workflow(workflow_config).await?;
println!("Workflow completed: {:?}", result);

🔐 Authentication

Environment Variables

Set your Veracode API credentials:

export VERACODE_API_ID="your-api-id"
export VERACODE_API_KEY="your-api-key"

Direct Configuration

Or pass credentials directly:

let config = VeracodeConfig::new(
    "your-api-id".to_string(),
    "your-api-key".to_string()
);

Development Mode

Disable certificate validation for development environments:

export VERASCAN_DISABLE_CERT_VALIDATION="true"

Or in code:

let config = VeracodeConfig::new("api_id".to_string(), "api_key".to_string())
    .with_certificate_validation_disabled(); // Only for development!

HashiCorp Vault Integration

For enhanced security in production environments, you can retrieve Veracode credentials from HashiCorp Vault using JWT/OIDC authentication:

# Required Vault environment variables
export VAULT_CLI_ADDR="https://vault.example.com"
export VAULT_CLI_JWT="your-jwt-token"
export VAULT_CLI_ROLE="veracode-role"
export VAULT_CLI_SECRET_PATH="secret/veracode/api"

# Optional: Custom auth path (default: auth/jwt)
export VAULT_CLI_AUTH_PATH="auth/jwt"         # Default JWT auth
export VAULT_CLI_AUTH_PATH="auth/oidc"        # Custom OIDC auth
export VAULT_CLI_AUTH_PATH="auth/kubernetes"  # Kubernetes auth
export VAULT_CLI_AUTH_PATH="jwt"              # Direct mount point

# Optional: Vault namespace (Enterprise only)
export VAULT_CLI_NAMESPACE="my-namespace"

The Vault secret must contain:

{
  "VERACODE_API_ID": "your-veracode-api-id",
  "VERACODE_API_KEY": "your-veracode-api-key"
}

Note: Vault integration is available in the verascan CLI application. See VAULT_INTEGRATION.md for detailed setup instructions.

🔄 Intelligent Retry Configuration

The library includes comprehensive retry functionality with exponential backoff for improved reliability and smart rate limit handling optimized for Veracode's 500 requests/minute limit:

Default Behavior

All HTTP operations automatically retry transient failures with intelligent rate limit handling:

use veracode_platform::{VeracodeConfig, VeracodeClient};

// Default configuration enables 5 retry attempts with exponential backoff
// and smart rate limit handling for Veracode's 500/minute limit
let config = VeracodeConfig::new(
    std::env::var("VERACODE_API_ID")?,
    std::env::var("VERACODE_API_KEY")?,
);
let client = VeracodeClient::new(config)?;

// All API calls automatically include intelligent retry logic  
let apps = client.get_all_applications().await?; // Optimally handles rate limits and network failures

Custom Retry Configuration

Fine-tune retry behavior for your specific needs:

use veracode_platform::{VeracodeConfig, RetryConfig};

let custom_retry = RetryConfig::new()
    .with_max_attempts(3)                    // 3 retry attempts (default: 5)
    .with_initial_delay(500)                 // Start with 500ms delay (default: 1000ms)
    .with_max_delay(60000)                   // Cap at 60 seconds (default: 30s)
    .with_backoff_multiplier(1.5)            // 1.5x growth factor (default: 2.0x)
    .with_max_total_delay(300000)            // 5 minutes total (default: 5 minutes)
    // New rate limiting options
    .with_rate_limit_buffer(10)              // 10s buffer for rate limit windows (default: 5s)
    .with_rate_limit_max_attempts(2);        // Max retries for 429 errors (default: 1)

let config = VeracodeConfig::new("api_id", "api_key")
    .with_retry_config(custom_retry);

let client = VeracodeClient::new(config)?;

Disable Retries

For scenarios requiring immediate error responses:

let config = VeracodeConfig::new("api_id", "api_key")
    .with_retries_disabled();  // No retries, immediate error on failure

let client = VeracodeClient::new(config)?;

Retry Behavior

The retry system intelligently handles different error types with specialized logic for rate limiting:

✅ Automatically Retried:

• Network timeouts and connection errors
• HTTP 429 "Too Many Requests" responses (with intelligent timing)
• HTTP 5xx server errors (500, 502, 503, 504)
• Temporary DNS resolution failures

❌ Not Retried (Immediate Failure):

• HTTP 4xx client errors (except 429)
• Authentication and authorization failures
• Invalid request format errors
• Configuration errors

Smart Rate Limit Handling

🚦 HTTP 429 Rate Limiting is handled with specialized logic optimized for Veracode's 500 requests/minute limit:

// When a 429 is encountered:
// 1. Parse Retry-After header if present
// 2. Calculate optimal wait time for Veracode's minute windows
// 3. Wait precisely until rate limit resets (no wasted attempts)
// 4. Only retry once by default (configurable)

// Example timing for 429 at different points in the minute:
// Hit 429 at second 15 → Wait ~50s (until next minute + 5s buffer)
// Hit 429 at second 45 → Wait ~20s (until next minute + 5s buffer)
// Hit 429 with Retry-After: 30 → Wait exactly 30s as instructed

Standard Exponential Backoff

For non-rate-limit errors, retry timing follows exponential backoff:

Attempt 1: Immediate
Attempt 2: 1 second delay
Attempt 3: 2 second delay  
Attempt 4: 4 second delay
Attempt 5: 8 second delay

With jitter and maximum delay caps to prevent overwhelming servers.

🚀 Rate Limiting Performance Benefits

The intelligent rate limit handling provides significant performance improvements over traditional exponential backoff:

Scenario	Traditional Approach	Smart Rate Limiting	Improvement
429 at second 45	Wait 1s, 2s, 4s, 8s, 16s (~31s total)	Wait ~20s (until next minute)	35% faster
429 at second 5	Wait 1s, 2s, 4s, 8s, 16s (~31s total)	Wait ~60s (until next minute)	Predictable timing
429 with Retry-After	Ignore header, use exponential backoff	Wait exactly as instructed	Server-guided optimal
Multiple 429s	4-5 failed attempts per rate limit	1 retry attempt per rate limit	4x fewer API calls

Key Benefits:

• ⚡ Faster Recovery: Targeted waits vs repeated failed attempts
• 🎯 Precise Timing: Wait exactly until rate limit resets
• 💾 Resource Efficient: No wasted API calls during rate limit windows
• 📊 Predictable: Deterministic delays based on actual rate limit timing
• 🔍 Clear Logging: Distinct messages for rate limits vs other failures

Example Log Output:

🚦 GET /appsec/v1/applications rate limited on attempt 1, waiting 45s (until next minute window)
✅ GET /appsec/v1/applications succeeded on attempt 2

⏱️ HTTP Timeout Configuration

The library provides configurable HTTP timeouts to handle different network conditions and operation requirements:

Default Timeouts

use veracode_platform::{VeracodeConfig, VeracodeClient};

// Default timeouts are applied automatically
let config = VeracodeConfig::new(
    std::env::var("VERACODE_API_ID")?,
    std::env::var("VERACODE_API_KEY")?,
);
// Default: 30 seconds connection timeout, 300 seconds (5 minutes) request timeout
let client = VeracodeClient::new(config)?;

Custom Timeout Configuration

Configure timeouts based on your specific needs:

use veracode_platform::{VeracodeConfig, VeracodeClient};

// Individual timeout configuration
let config = VeracodeConfig::new("api_id", "api_key")
    .with_connect_timeout(60)      // 60 seconds to establish connection
    .with_request_timeout(900);    // 15 minutes total request timeout

// Convenience method for both timeouts
let config = VeracodeConfig::new("api_id", "api_key")
    .with_timeouts(120, 1800);     // 2 minutes connect, 30 minutes request

let client = VeracodeClient::new(config)?;

Timeout Types

Timeout Type	Default	Description
Connection Timeout	30 seconds	Maximum time to establish TCP connection
Request Timeout	300 seconds (5 minutes)	Total time for complete request/response cycle

Use Case Examples

Standard API Operations:

let config = VeracodeConfig::new("api_id", "api_key")
    .with_timeouts(30, 300);  // Default values - good for most operations

Large File Uploads:

let config = VeracodeConfig::new("api_id", "api_key")
    .with_timeouts(120, 1800);  // Extended timeouts for large files (30 minutes)

High-Performance/Low-Latency:

let config = VeracodeConfig::new("api_id", "api_key")
    .with_timeouts(10, 60);  // Aggressive timeouts for fast operations

Development/Testing:

let config = VeracodeConfig::new("api_id", "api_key")
    .with_timeouts(5, 30);  // Short timeouts to catch issues quickly

Combined with Retry Configuration

Timeouts work seamlessly with retry configuration:

use veracode_platform::{VeracodeConfig, RetryConfig};

let retry_config = RetryConfig::new()
    .with_max_attempts(3)
    .with_initial_delay(1000);

let config = VeracodeConfig::new("api_id", "api_key")
    .with_timeouts(60, 300)           // Custom timeouts
    .with_retry_config(retry_config); // Custom retry behavior

// Each retry attempt respects the timeout configuration
let client = VeracodeClient::new(config)?;

Method Chaining

All timeout methods support fluent configuration:

let config = VeracodeConfig::new("api_id", "api_key")
    .with_region(VeracodeRegion::European)    // Set region
    .with_connect_timeout(45)                 // 45s connection timeout
    .with_request_timeout(600)                // 10 minute request timeout
    .with_retries_disabled();                 // Disable retries

let client = VeracodeClient::new(config)?;

⚡ Performance Optimizations

The library includes advanced performance optimizations for high-throughput applications:

Memory Allocation Efficiency

Copy-on-Write (Cow) Patterns: Operation names and dynamic strings use Cow<str> to defer allocations until necessary, reducing memory pressure by ~60% in retry scenarios.

String Pre-allocation: URL building uses String::with_capacity() to eliminate heap reallocations, improving performance by ~40% for repeated requests.

Request Body Optimization: JSON serialization occurs once per retry sequence rather than per-attempt, significantly improving performance for large payloads.

Smart Resource Management

Authentication Constants: Static error message strings prevent repeated allocations, reducing authentication error handling overhead by 4x.

Smart Operation Naming: Short endpoints use formatted strings while long endpoints use static references to avoid unnecessary allocations.

Memory-Efficient Error Handling: Streamlined error message creation with minimal string formatting in hot paths.

Real-World Performance Impact

Network Retry Scenarios (most common use case):

• 60% fewer allocations in retry hot paths
• 40% reduction in memory pressure during network failures
• 3x less memory usage for 5 retry attempts with network errors

High-Throughput Operations:

• Pre-allocated URL building eliminates repeated heap growth
• Zero-cost abstractions maintain API ergonomics
• Efficient request body handling for large payloads (>1MB)

All optimizations maintain 100% API compatibility while delivering significant performance improvements under load.

🎛️ Feature Flags

Enable only the APIs you need to reduce compile time and binary size:

[dependencies]
veracode-platform = { version = "0.1.0", features = ["pipeline", "applications"] }

Available features:

• applications - Applications API support
• identity - Identity API support
• pipeline - Pipeline Scan API support
• sandbox - Sandbox API support
• policy - Policy API support
• default - All APIs enabled

🧪 Examples

The library includes comprehensive examples for each API:

# Set up credentials first
export VERACODE_API_ID="your-api-id"
export VERACODE_API_KEY="your-api-key"

# Applications API example
cargo run --example application_lifecycle

# Identity API example
cargo run --example identity_lifecycle

# Pipeline Scan API example
cargo run --example pipeline_scan_lifecycle

# Sandbox API example
cargo run --example sandbox_lifecycle

# Policy API example
cargo run --example policy_lifecycle

# Basic usage example
cargo run --example basic_usage

# Build lifecycle example
cargo run --example build_lifecycle_example

# Large file upload example
cargo run --example large_file_upload_example

# XML API workflow validation
cargo run --example xml_api_workflow_validation

🏗️ Architecture

API Type Routing

The library automatically routes operations to the correct API type:

• REST API (api.veracode.*): Applications, Identity, Pipeline, Policy, Sandbox management
• XML API (analysiscenter.veracode.*): Build management, Scan operations, Legacy workflows

Smart Client Management

The client automatically creates specialized instances for different API types:

let client = VeracodeClient::new(config)?;

// REST API modules use the main client
let apps = client.get_all_applications().await?;  // Uses REST
let pipeline = client.pipeline_api();             // Uses REST
let identity = client.identity_api();             // Uses REST

// XML API modules use a specialized XML client internally
let scan_api = client.scan_api();                 // Uses XML
let build_api = client.build_api();               // Uses XML

Regional Endpoint Management

All regional variants are supported with automatic endpoint resolution:

Region	REST Endpoint	XML Endpoint
Commercial	api.veracode.com	analysiscenter.veracode.com
European	api.veracode.eu	analysiscenter.veracode.eu
Federal	api.veracode.us	analysiscenter.veracode.us

🔐 Security Features

Secure Credential Handling

All API credentials are automatically secured to prevent accidental exposure:

use veracode_platform::{VeracodeConfig, VeracodeClient};

// Credentials are automatically wrapped in secure containers
let config = VeracodeConfig::new(
    std::env::var("VERACODE_API_ID")?,
    std::env::var("VERACODE_API_KEY")?,
);

// Debug output shows [REDACTED] instead of actual credentials
println!("{:?}", config);
// Output: VeracodeConfig { api_id: [REDACTED], api_key: [REDACTED], ... }

Debug Safety

All sensitive information is automatically redacted in debug output:

• API Credentials: VERACODE_API_ID and VERACODE_API_KEY show as [REDACTED]
• Configuration Structures: VeracodeConfig safely displays structure without exposing credentials
• Identity API: ApiCredential structures redact sensitive api_key fields
• Comprehensive Coverage: All credential-containing structures are protected

Backward Compatibility

All improvements are transparent to existing code:

• All existing examples continue to work unchanged
• No breaking changes to public APIs
• Rate limiting improvements are automatically applied to all requests
• New VeracodeError::RateLimited variant added (non-breaking addition)
• New rate limit configuration options available but not required
• Secure wrappers are internal implementation details
• Access to credentials through standard methods (as_str(), into_string())

🔧 Error Handling

The library provides comprehensive error types for robust error handling:

use veracode_platform::{VeracodeError, pipeline::PipelineError, sandbox::SandboxError};

// Pipeline API error handling
match pipeline.get_findings(&scan_id).await {
    Ok(findings) => println!("Found {} issues", findings.len()),
    Err(PipelineError::FindingsNotReady) => {
        println!("Scan still processing, try again later");
    },
    Err(PipelineError::ApiError(VeracodeError::Unauthorized)) => {
        println!("Check your API credentials");
    },
    Err(PipelineError::ApiError(VeracodeError::NotFound(msg))) => {
        println!("Scan not found: {}", msg);
    },
    Err(e) => println!("Error: {}", e),
}

// Sandbox API error handling
match sandbox_api.get_sandboxes("app-guid").await {
    Ok(sandboxes) => println!("Found {} sandboxes", sandboxes.len()),
    Err(SandboxError::InvalidApplicationGuid(guid)) => {
        println!("Invalid application GUID: {}", guid);
    },
    Err(SandboxError::ApiError(VeracodeError::Authentication(msg))) => {
        println!("Authentication failed: {}", msg);
    },
    Err(e) => println!("Error: {}", e),
}

Common Error Types

Error Type	Description
VeracodeError::Authentication	Invalid API credentials or signature issues
VeracodeError::NotFound	Requested resource doesn't exist
VeracodeError::InvalidResponse	API returned unexpected response format
VeracodeError::Http	Network or HTTP-level errors
VeracodeError::Serialization	JSON parsing or serialization errors
VeracodeError::RateLimited	HTTP 429 rate limit exceeded - includes server's suggested retry timing
VeracodeError::RetryExhausted	All retry attempts failed - includes detailed timing and error information

Retry Error Handling

The retry system provides detailed error information when all attempts are exhausted:

use veracode_platform::{VeracodeError};

match client.get_all_applications().await {
    Ok(apps) => println!("Found {} applications", apps.len()),
    Err(VeracodeError::RetryExhausted(msg)) => {
        // Detailed error with attempt count and timing
        println!("Request failed after all retries: {}", msg);
        // Example: "GET /appsec/v1/applications failed after 5 attempts over 15234ms: Connection timeout"
    },
    Err(VeracodeError::RateLimited { retry_after_seconds, message }) => {
        // Rate limit errors with timing information
        match retry_after_seconds {
            Some(seconds) => println!("Rate limited: {} (retry after {}s)", message, seconds),
            None => println!("Rate limited: {} (window-based)", message),
        }
    },
    Err(VeracodeError::Authentication(msg)) => {
        // Authentication errors are not retried
        println!("Authentication failed immediately: {}", msg);
    },
    Err(e) => println!("Other error: {}", e),
}

📊 Data Types

Core Types

// Application management
pub struct Application {
    pub guid: String,
    pub name: String,
    pub description: Option<String>,
    // ... more fields
}

// Pipeline scanning
pub struct Finding {
    pub issue_id: u32,
    pub issue_type: String,
    pub issue_type_id: String,
    pub cwe_id: String,
    pub severity: Severity,
    // ... more fields
}

// Identity management
pub struct User {
    pub user_id: String,
    pub email: String,
    pub first_name: String,
    pub last_name: String,
    pub user_type: UserType,
    // ... more fields
}

Enums and Status Types

// Scan status tracking
#[derive(Debug, Clone, PartialEq)]
pub enum ScanStatus {
    Pending,
    Running,
    Complete,
    Failed,
    Cancelled,
}

// Security severity levels
#[derive(Debug, Clone, PartialEq)]
pub enum Severity {
    VeryHigh,
    High,
    Medium,
    Low,
    VeryLow,
    Informational,
}

// Development stages
#[derive(Debug, Clone, PartialEq)]
pub enum DevStage {
    Development,
    Testing,
    Release,
}

🔬 Testing

Run the test suite:

# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# Run specific test module
cargo test --test applications_api

Note: Integration tests require valid Veracode API credentials and may create/modify resources in your Veracode account.

📖 Documentation

Generate and view the documentation:

# Build and open documentation
cargo doc --open

# Build documentation for all features
cargo doc --all-features --open

🏷️ Versioning

This library follows Semantic Versioning:

• Major version changes indicate breaking API changes
• Minor version changes add functionality in a backward-compatible manner
• Patch version changes include backward-compatible bug fixes

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone the repository
git clone <repository-url>
cd veracode-workspace/veracode-api

# Run tests
cargo test

# Check formatting
cargo fmt -- --check

# Run lints
cargo clippy -- -D warnings

# Build documentation
cargo doc --all-features

📜 License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

🆘 Support

• 📚 Documentation: docs.rs/veracode-platform
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📝 Changelog: CHANGELOG.md

---

Built with ❤️ in Rust for the security community