Exceptions

The Community DevOps Agent API defines custom exceptions for different error conditions.

Overview

The library provides specific exception types for different error scenarios:

  • API Errors: Errors from the DevOps Agent API

  • Authentication Errors: Credential and permission issues

  • Validation Errors: Data validation failures

  • Configuration Errors: Setup and configuration problems

Exception Hierarchy

Exception classes for the DevOps Agent API.

This module provides a comprehensive exception hierarchy that extends botocore’s exception system while adding DevOps Agent specific error handling.

exception devopsagent_api.exceptions.DevOpsAgentError(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: ClientError

Base exception class for DevOps Agent API errors.

This extends botocore’s ClientError to provide a common base for all DevOps Agent specific exceptions while maintaining compatibility with boto3’s exception handling patterns.

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

property error_code: str | None

Get the error code from the response.

property error_message: str | None

Get the error message from the response.

property http_status_code: int | None

Get the HTTP status code.

property request_id: str | None

Get the AWS request ID.

__str__() → str[source]

String representation of the error.

exception devopsagent_api.exceptions.AuthenticationError(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: DevOpsAgentError

Authentication-related errors.

Raised when there are issues with AWS credentials, JWT generation, or credential exchange authentication flow.

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.CredentialRefreshError(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: AuthenticationError

Credential refresh errors.

Raised when automatic credential refresh fails, typically due to: - Expired AWS credentials - Network connectivity issues - Invalid agent space configuration - API service unavailability

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.JWTGenerationError(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: AuthenticationError

JWT token generation errors.

Raised when JWT token generation fails, typically due to: - Invalid AWS credentials - Insufficient IAM permissions - Network connectivity issues - Control plane API unavailability

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.CredentialExchangeError(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: AuthenticationError

Credential exchange errors.

Raised when JWT to temporary credential exchange fails, typically due to: - Expired or invalid JWT token - Authorizer service unavailability - Invalid agent space ID - Cookie/session issues

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.ConfigurationError(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: DevOpsAgentError

Configuration and setup errors.

Raised when there are issues with library configuration, typically due to: - Missing or invalid service model files - Incorrect boto3 integration - Invalid region or endpoint configuration - Package installation issues

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.ServiceRegistrationError(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: ConfigurationError

Service registration errors.

Raised when the boto3 service registration fails, typically due to: - Missing service model files - Botocore integration issues - Import or initialization failures

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.ModelValidationError(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: ConfigurationError

Model validation errors.

Raised when Pydantic model validation fails, typically due to: - Invalid data types - Missing required fields - Constraint violations - Schema mismatches

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.ValidationException(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: DevOpsAgentError

Request validation errors.

Corresponds to HTTP 400 errors from the API, raised when: - Required parameters are missing - Parameter values are invalid - Request format is incorrect - Business rule violations

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.UnauthorizedException(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: DevOpsAgentError

Authentication and authorization errors.

Corresponds to HTTP 401/403 errors from the API, raised when: - Invalid or missing credentials - Insufficient permissions - Expired authentication - Invalid agent space access

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.ResourceNotFoundException(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: DevOpsAgentError

Resource not found errors.

Corresponds to HTTP 404 errors from the API, raised when: - Task ID does not exist - Agent space ID is invalid - Recommendation ID not found - Execution ID is missing

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.ConflictException(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: DevOpsAgentError

Resource conflict errors.

Corresponds to HTTP 409 errors from the API, raised when: - Resource already exists - Version conflicts in updates - Concurrent modification issues

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.ThrottlingException(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: DevOpsAgentError

Rate limiting errors.

Corresponds to HTTP 429 errors from the API, raised when: - Request rate exceeds limits - Burst limits exceeded - Backoff required

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.InternalServerException(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: DevOpsAgentError

Internal server errors.

Corresponds to HTTP 500 errors from the API, raised when: - Unexpected server errors - Service unavailability - Database or backend issues

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.ServiceUnavailableException(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: DevOpsAgentError

Service unavailable errors.

Corresponds to HTTP 503 errors from the API, raised when: - Service maintenance - Temporary outages - Capacity issues

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

exception devopsagent_api.exceptions.NetworkError(**kwargs)[source]

Bases: BotoCoreError

Network and connectivity errors.

Extends BotoCoreError for network-related issues that occur before reaching the API service.

exception devopsagent_api.exceptions.ConnectionError(**kwargs)[source]

Bases: NetworkError

Connection establishment errors.

Raised when unable to establish connection to API endpoints, typically due to: - DNS resolution failures - Network connectivity issues - Firewall or proxy problems - SSL/TLS handshake failures

exception devopsagent_api.exceptions.TimeoutError(**kwargs)[source]

Bases: NetworkError

Request timeout errors.

Raised when requests exceed configured timeouts, typically due to: - Slow network connections - API service overload - Large response payloads - Network congestion

devopsagent_api.exceptions.handle_client_error(error: ClientError) → DevOpsAgentError[source]

Convert botocore ClientError to DevOpsAgentError.

This utility function takes a standard botocore ClientError and converts it to the appropriate DevOpsAgentError subclass.

Parameters:

error – Original ClientError from botocore

Returns:

Appropriate DevOpsAgentError subclass

Raises:

DevOpsAgentError – Converted exception

Base Exception

All custom exceptions inherit from DevOpsAgentError:

class devopsagent_api.exceptions.DevOpsAgentError(error_response: Dict[str, Any], operation_name: str, service_name: str = 'community-devops-agent', **kwargs)[source]

Bases: ClientError

Base exception class for DevOps Agent API errors.

This extends botocore’s ClientError to provide a common base for all DevOps Agent specific exceptions while maintaining compatibility with boto3’s exception handling patterns.

Initialize the DevOps Agent error.

Parameters:

  • error_response – Error response dictionary

  • operation_name – Name of the operation that failed

  • service_name – Service name (defaults to community-devops-agent)

  • **kwargs – Additional arguments passed to ClientError

property error_code: str | None

Get the error code from the response.

property error_message: str | None

Get the error message from the response.

property http_status_code: int | None

Get the HTTP status code.

property request_id: str | None

Get the AWS request ID.

__str__() → str[source]

String representation of the error.

API Exceptions

DevOpsAgentAPIError

Raised for API-related errors:

Common Causes: - Invalid API parameters - Resource not found - Service unavailable - Rate limiting

Authentication Exceptions

DevOpsAgentAuthError

Raised for authentication and authorization failures:

Common Causes: - Invalid AWS credentials - Insufficient permissions - Expired credentials - Region mismatch

Validation Exceptions

DevOpsAgentValidationError

Raised for data validation errors:

Common Causes: - Invalid parameter values - Missing required fields - Type mismatches - Constraint violations

Configuration Exceptions

DevOpsAgentConfigError

Raised for configuration-related issues:

Common Causes: - Missing environment variables - Invalid configuration values - Service registration failures

Error Handling Patterns

Basic Error Handling

from devopsagent_api.exceptions import DevOpsAgentError

try:
    # API call
    response = client.list_tasks()
except DevOpsAgentError as e:
    print(f"DevOps Agent error: {e}")
    # Handle the error

Specific Exception Handling

from devopsagent_api.exceptions import (
    DevOpsAgentAPIError,
    DevOpsAgentAuthError,
    DevOpsAgentValidationError,
    DevOpsAgentConfigError
)

try:
    response = client.get_task(task_id="invalid-id")
except DevOpsAgentAPIError as e:
    print(f"API error: {e}")
except DevOpsAgentAuthError as e:
    print(f"Authentication error: {e}")
except DevOpsAgentValidationError as e:
    print(f"Validation error: {e}")
except DevOpsAgentConfigError as e:
    print(f"Configuration error: {e}")

Logging Errors

import logging
from devopsagent_api.exceptions import DevOpsAgentError

logger = logging.getLogger(__name__)

try:
    response = client.create_task(title="")
except DevOpsAgentError as e:
    logger.error(f"DevOps Agent operation failed: {e}", exc_info=True)
    raise

Error Context

Exceptions include additional context:

try:
    response = client.list_tasks(agentSpaceId="invalid-uuid")
except DevOpsAgentAPIError as e:
    print(f"Error code: {e.code}")
    print(f"HTTP status: {e.status_code}")
    print(f"Request ID: {e.request_id}")
    print(f"Details: {e.details}")

Best Practices

Catch Specific Exceptions

# Good - catch specific exceptions
try:
    client.create_task(title="Test")
except DevOpsAgentValidationError:
    # Handle validation errors
    pass
except DevOpsAgentAuthError:
    # Handle auth errors
    pass

# Avoid - catch generic exception
try:
    client.create_task(title="Test")
except Exception:  # Too broad
    pass

Log Errors Appropriately

# Good - log with context
try:
    response = client.get_task(task_id)
except DevOpsAgentAPIError as e:
    logger.error(f"Failed to get task {task_id}: {e}", exc_info=True)

# Avoid - not logging errors
try:
    response = client.get_task(task_id)
except DevOpsAgentAPIError:
    pass  # Silent failure

Preserve Exception Context

# Good - re-raise with context
try:
    response = client.list_tasks()
except DevOpsAgentError:
    logger.error("Task listing failed")
    raise  # Preserve original exception

# Avoid - lose original exception
try:
    response = client.list_tasks()
except DevOpsAgentError as e:
    raise RuntimeError("Task listing failed")  # Loses original

Handle Retries

import time
from devopsagent_api.exceptions import DevOpsAgentAPIError

max_retries = 3
for attempt in range(max_retries):
    try:
        response = client.list_tasks()
        break
    except DevOpsAgentAPIError as e:
        if e.status_code == 429:  # Rate limited
            time.sleep(2 ** attempt)  # Exponential backoff
            continue
        raise

Error Codes

Common error codes and their meanings:

API Errors (4xx)

  • 400: Bad Request - Invalid parameters

  • 401: Unauthorized - Authentication required

  • 403: Forbidden - Insufficient permissions

  • 404: Not Found - Resource doesn’t exist

  • 429: Too Many Requests - Rate limited

Server Errors (5xx)

  • 500: Internal Server Error

  • 502: Bad Gateway

  • 503: Service Unavailable

  • 504: Gateway Timeout

Client Errors

  • CONFIG_ERROR: Configuration issue

  • VALIDATION_ERROR: Data validation failure

  • AUTH_ERROR: Authentication failure

  • NETWORK_ERROR: Network connectivity issue

Troubleshooting

Debugging Errors

Enable debug logging to see detailed error information:

import logging

logging.basicConfig(level=logging.DEBUG)

# This will show detailed error traces
try:
    response = client.list_tasks()
except DevOpsAgentError as e:
    print(f"Error: {e}")
    print(f"Details: {e.details}")

Common Issues

Authentication Errors

# Check AWS credentials
aws sts get-caller-identity

# Verify region
aws configure list

Permission Errors

Ensure your IAM user/role has the necessary permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "devops-agent:ListTasks",
                "devops-agent:GetTask",
                "devops-agent:CreateTask"
            ],
            "Resource": "*"
        }
    ]
}

Network Issues

Check network connectivity and DNS resolution:

# Test connectivity
curl -I https://devops-agent.us-east-1.amazonaws.com

# Check DNS
nslookup devops-agent.us-east-1.amazonaws.com