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
-------------------

.. automodule:: devopsagent_api.exceptions
   :members:
   :undoc-members:
   :show-inheritance:

Base Exception
--------------

All custom exceptions inherit from ``DevOpsAgentError``:

.. autoclass:: devopsagent_api.exceptions.DevOpsAgentError
   :members:
   :undoc-members:
   :show-inheritance:

API Exceptions
--------------

**DevOpsAgentAPIError**

Raised for API-related errors:

.. autoclass:: devopsagent_api.exceptions.DevOpsAgentAPIError
   :members:
   :undoc-members:
   :show-inheritance:

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

Authentication Exceptions
-------------------------

**DevOpsAgentAuthError**

Raised for authentication and authorization failures:

.. autoclass:: devopsagent_api.exceptions.DevOpsAgentAuthError
   :members:
   :undoc-members:
   :show-inheritance:

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

Validation Exceptions
---------------------

**DevOpsAgentValidationError**

Raised for data validation errors:

.. autoclass:: devopsagent_api.exceptions.DevOpsAgentValidationError
   :members:
   :undoc-members:
   :show-inheritance:

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

Configuration Exceptions
------------------------

**DevOpsAgentConfigError**

Raised for configuration-related issues:

.. autoclass:: devopsagent_api.exceptions.DevOpsAgentConfigError
   :members:
   :undoc-members:
   :show-inheritance:

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

Error Handling Patterns
-----------------------

**Basic Error Handling**

.. code-block:: python

   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**

.. code-block:: python

   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**

.. code-block:: python

   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:

.. code-block:: python

   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**

.. code-block:: python

   # 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**

.. code-block:: python

   # 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**

.. code-block:: python

   # 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**

.. code-block:: python

   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:

.. code-block:: python

   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**

.. code-block:: bash

   # Check AWS credentials
   aws sts get-caller-identity

   # Verify region
   aws configure list

**Permission Errors**

Ensure your IAM user/role has the necessary permissions:

.. code-block:: json

   {
       "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:

.. code-block:: bash

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

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