Error Handling
==============

The YouTrack CLI provides standardized error formatting across all commands with support for both interactive and automation use cases.

Error Format
------------

Standard Error Format
~~~~~~~~~~~~~~~~~~~~~~

In normal mode, errors are displayed with clear visual indicators::

    ❌ Authentication failed [AUTH_001]
    Details: Invalid token format

Quiet Mode Format
~~~~~~~~~~~~~~~~~

In quiet mode (``--quiet`` or ``-q``), errors are displayed in a format suitable for automation::

    AUTH_001: Authentication failed

Error Codes
-----------

The CLI uses a standardized error code system for programmatic handling:

Authentication Errors (AUTH_xxx)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ``AUTH_001`` - Authentication failed
* ``AUTH_002`` - Authentication expired
* ``AUTH_003`` - Invalid token format
* ``AUTH_004`` - No authentication credentials found

Network Errors (NET_xxx)
~~~~~~~~~~~~~~~~~~~~~~~~~

* ``NET_001`` - Connection failed
* ``NET_002`` - Request timeout
* ``NET_003`` - SSL/TLS error
* ``NET_004`` - DNS resolution error

Validation Errors (VAL_xxx)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ``VAL_001`` - Invalid input format
* ``VAL_002`` - Missing required field
* ``VAL_003`` - Format validation error
* ``VAL_004`` - Value out of range

Permission Errors (PERM_xxx)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ``PERM_001`` - Access denied
* ``PERM_002`` - Insufficient privileges
* ``PERM_003`` - Resource forbidden

Configuration Errors (CFG_xxx)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ``CFG_001`` - Configuration not found
* ``CFG_002`` - Invalid configuration format
* ``CFG_003`` - Configuration save failed
* ``CFG_004`` - Configuration load failed

Resource Errors (RES_xxx)
~~~~~~~~~~~~~~~~~~~~~~~~~~

* ``RES_001`` - Resource not found
* ``RES_002`` - Resource already exists
* ``RES_003`` - Operation failed

System Errors (SYS_xxx)
~~~~~~~~~~~~~~~~~~~~~~~~

* ``SYS_001`` - Internal system error
* ``SYS_002`` - Unsupported operation
* ``SYS_003`` - Filesystem error

Generic Errors (GEN_xxx)
~~~~~~~~~~~~~~~~~~~~~~~~~

* ``GEN_001`` - Unknown error
* ``GEN_002`` - Operation cancelled

Usage Examples
--------------

Interactive Mode
~~~~~~~~~~~~~~~~

For interactive use, run commands normally to see user-friendly error messages::

    $ yt issues list
    ❌ No authentication credentials found [AUTH_004]
    Details: Run 'yt auth login' to authenticate first

Automation Mode
~~~~~~~~~~~~~~~

For automation and scripting, use the ``--quiet`` flag::

    $ yt --quiet issues list
    AUTH_004: No authentication credentials found

Error Handling in Scripts
~~~~~~~~~~~~~~~~~~~~~~~~~~

Parse error codes programmatically::

    #!/bin/bash
    output=$(yt --quiet issues list 2>&1)
    if [[ $? -ne 0 ]]; then
        error_code=$(echo "$output" | cut -d':' -f1)
        case $error_code in
            "AUTH_004")
                echo "Need to authenticate first"
                yt auth login
                ;;
            "NET_001")
                echo "Connection failed, check network"
                ;;
            *)
                echo "Unknown error: $output"
                ;;
        esac
    fi

Global Options
--------------

Quiet Mode
~~~~~~~~~~

Enable quiet mode for automation-friendly output::

    yt --quiet <command>
    yt -q <command>

Quiet mode:

* Removes emojis and styling
* Uses plain text format
* Provides error codes for programmatic handling
* Cannot be used with ``--verbose``

Verbose Mode
~~~~~~~~~~~~

Enable verbose mode for detailed output::

    yt --verbose <command>
    yt -v <command>

Verbose mode:

* Shows detailed error information
* Includes additional context
* Cannot be used with ``--quiet``

Developer Guide
---------------

Using Standardized Errors
~~~~~~~~~~~~~~~~~~~~~~~~~~

When developing commands, use the standardized error system::

    from youtrack_cli.error_formatting import CommonErrors, format_and_print_error

    # Use common error patterns
    format_and_print_error(CommonErrors.authentication_failed(details="Token expired"))

    # Create custom errors
    from youtrack_cli.error_formatting import StandardizedError, ErrorCode

    error = StandardizedError(
        code=ErrorCode.VAL_INVALID_INPUT,
        message="Invalid project ID format",
        details="Project ID must match pattern: [A-Z]{2,}-\\d+"
    )
    format_and_print_error(error)

Error Severity Levels
~~~~~~~~~~~~~~~~~~~~~

Errors support different severity levels::

    from youtrack_cli.error_formatting import ErrorSeverity

    # Warning level
    warning = StandardizedError(
        code=ErrorCode.CFG_INVALID_FORMAT,
        message="Deprecated configuration format",
        severity=ErrorSeverity.WARNING
    )

    # Error level (default)
    error = StandardizedError(
        code=ErrorCode.AUTH_FAILED,
        message="Authentication failed"
    )

Migration Guide
---------------

Legacy Error Patterns
~~~~~~~~~~~~~~~~~~~~~~

Old error patterns::

    console.print(f"❌ Authentication failed: {error}", style="red")

New standardized patterns::

    format_and_print_error(CommonErrors.authentication_failed(details=error))

Backward Compatibility
~~~~~~~~~~~~~~~~~~~~~~~

The system provides backward compatibility through legacy functions::

    from youtrack_cli.error_formatting import print_legacy_error

    # This works but should be migrated
    print_legacy_error("Operation failed")