Skip to content

codes

codes

Error codes, categories, and severity levels.

Contains the structured error classification enums used throughout Marianne.

This module provides: - ExitReason: Type alias for process exit reasons - RetryDelays: Constants for retry timing - Severity: Severity levels for error classification - RetryBehavior: Precise retry recommendations per error code - ErrorCode: Structured error codes (E0xx-E9xx) - ErrorCategory: High-level categories for retry behavior

Error Code Taxonomy

Marianne uses a structured error code system organized by category prefixes. Each error code provides specific retry behavior guidance.

E0xx - Execution Errors Process-level failures during command execution.

| Code | Name | Retriable | Severity | Default Delay |
|------|------|-----------|----------|---------------|
| E001 | EXECUTION_TIMEOUT | Yes | ERROR | 60s |
| E002 | EXECUTION_KILLED | Yes | ERROR | 30s |
| E003 | EXECUTION_CRASHED | No | CRITICAL | N/A |
| E004 | EXECUTION_INTERRUPTED | No | ERROR | N/A |
| E005 | EXECUTION_OOM | No | CRITICAL | N/A |
| E006 | EXECUTION_STALE | Yes | WARNING | 120s |
| E009 | EXECUTION_UNKNOWN | Yes | ERROR | 10s |

E1xx - Rate Limit / Capacity Errors API throttling and resource exhaustion.

| Code | Name | Retriable | Severity | Default Delay |
|------|------|-----------|----------|---------------|
| E101 | RATE_LIMIT_API | Yes | ERROR | 1 hour |
| E102 | RATE_LIMIT_CLI | Yes | ERROR | 15 min |
| E103 | CAPACITY_EXCEEDED | Yes | WARNING | 5 min |
| E104 | QUOTA_EXHAUSTED | Yes | ERROR | Dynamic* |

*E104 delay is parsed from API response reset time.

E2xx - Validation Errors Output validation failures (retriable - LLM may produce correct output).

| Code | Name | Retriable | Severity | Default Delay |
|------|------|-----------|----------|---------------|
| E201 | VALIDATION_FILE_MISSING | Yes | ERROR | 5s |
| E202 | VALIDATION_CONTENT_MISMATCH | Yes | ERROR | 5s |
| E203 | VALIDATION_COMMAND_FAILED | Yes | ERROR | 10s |
| E204 | VALIDATION_TIMEOUT | Yes | WARNING | 30s |
| E209 | VALIDATION_GENERIC | Yes | ERROR | 5s |

E3xx - Configuration Errors Job configuration problems (not retriable - requires user fix).

| Code | Name | Retriable | Severity |
|------|------|-----------|----------|
| E301 | CONFIG_INVALID | No | ERROR |
| E302 | CONFIG_MISSING_FIELD | No | ERROR |
| E303 | CONFIG_PATH_NOT_FOUND | No | ERROR |
| E304 | CONFIG_PARSE_ERROR | No | ERROR |
| E305 | CONFIG_MCP_ERROR | No | ERROR |
| E306 | CONFIG_CLI_MODE_ERROR | No | ERROR |

E4xx - State Errors Checkpoint state issues.

| Code | Name | Retriable | Severity |
|------|------|-----------|----------|
| E401 | STATE_CORRUPTION | No | CRITICAL |
| E402 | STATE_LOAD_FAILED | Yes | ERROR |
| E403 | STATE_SAVE_FAILED | Yes | ERROR |
| E404 | STATE_VERSION_MISMATCH | No | ERROR |

E5xx - Backend Errors Backend service/connection issues.

| Code | Name | Retriable | Severity | Default Delay |
|------|------|-----------|----------|---------------|
| E501 | BACKEND_CONNECTION | Yes | ERROR | 30s |
| E502 | BACKEND_AUTH | No | CRITICAL | N/A |
| E503 | BACKEND_RESPONSE | Yes | ERROR | 15s |
| E504 | BACKEND_TIMEOUT | Yes | ERROR | 60s |
| E505 | BACKEND_NOT_FOUND | No | CRITICAL | N/A |

E6xx - Preflight Errors Pre-execution validation failures (not retriable).

| Code | Name | Retriable | Severity |
|------|------|-----------|----------|
| E601 | PREFLIGHT_PATH_MISSING | No | ERROR |
| E602 | PREFLIGHT_PROMPT_TOO_LARGE | No | ERROR |
| E603 | PREFLIGHT_WORKING_DIR_INVALID | No | ERROR |
| E604 | PREFLIGHT_VALIDATION_SETUP | No | ERROR |

E9xx - Network/Transient Errors Network connectivity and transient failures.

| Code | Name | Retriable | Severity | Default Delay |
|------|------|-----------|----------|---------------|
| E901 | NETWORK_CONNECTION_FAILED | Yes | ERROR | 30s |
| E902 | NETWORK_DNS_ERROR | Yes | ERROR | 30s |
| E903 | NETWORK_SSL_ERROR | Yes | ERROR | 30s |
| E904 | NETWORK_TIMEOUT | Yes | ERROR | 60s |
| E999 | UNKNOWN | Yes | ERROR | 30s |

Usage

Error codes are used throughout Marianne for: - Programmatic routing: Switch on error_code.category for handling logic - Retry decisions: Use error_code.get_retry_behavior() for delay/retriability - Logging/metrics: Structured error codes enable aggregation and alerting - User guidance: Error codes map to documentation and troubleshooting guides

Example::

result = error_classifier.classify(stdout, stderr, exit_code)
if result.primary.error_code.category == "rate_limit":
    delay = result.primary.error_code.get_retry_behavior().delay_seconds
    await asyncio.sleep(delay)

Classes

RetryDelays

Constants for retry delay durations.

Centralizes magic numbers for retry timing to ensure consistency across the codebase and make timing decisions discoverable.

These values represent standard delays for different error scenarios. Actual delays may be adjusted dynamically based on error context, parsed reset times, or learning from previous attempts.

Severity

Bases: IntEnum

Severity levels for error classification.

Lower numeric value = higher severity. This allows comparisons like if severity <= Severity.ERROR to check for serious issues.

Assignments: - CRITICAL: Job cannot continue, requires immediate attention (E003 crash, E005 OOM, E401 corruption, E502 auth, E505 binary not found) - ERROR: Operation failed, may be retriable (most error codes) - WARNING: Degraded operation, job may continue (E103 capacity, E204 validation timeout) - INFO: Informational, no action required (reserved for future diagnostic codes)

RetryBehavior

Bases: NamedTuple

Precise retry behavior recommendation for a specific error code.

Unlike ErrorCategory which provides broad retry guidelines, RetryBehavior encodes error-code-specific knowledge about optimal retry strategies.

Attributes:

Name Type Description
delay_seconds float

Recommended delay before retrying (0 = no delay).
is_retriable bool

Whether this error is generally retriable.
reason str

Human-readable explanation for the retry behavior.

ErrorCode

Bases: str, Enum

Structured error codes for comprehensive error classification.

Error codes are organized by category using numeric prefixes: - E0xx: Execution errors (timeouts, crashes, kills) - E1xx: Rate limit / capacity errors - E2xx: Validation errors - E3xx: Configuration errors - E4xx: State errors - E5xx: Backend errors - E6xx: Preflight errors

Error codes are stable identifiers that can be used for: - Programmatic error handling and routing - Log aggregation and alerting - Documentation and troubleshooting guides - Metrics and observability dashboards

Attributes
EXECUTION_TIMEOUT class-attribute instance-attribute 
EXECUTION_TIMEOUT = 'E001'

Command execution exceeded timeout limit.

EXECUTION_KILLED class-attribute instance-attribute 
EXECUTION_KILLED = 'E002'

Process was killed by a signal (external termination).

EXECUTION_CRASHED class-attribute instance-attribute 
EXECUTION_CRASHED = 'E003'

Process crashed (segfault, bus error, abort, etc.).

EXECUTION_INTERRUPTED class-attribute instance-attribute 
EXECUTION_INTERRUPTED = 'E004'

Process was interrupted by user (SIGINT/Ctrl+C).

EXECUTION_OOM class-attribute instance-attribute 
EXECUTION_OOM = 'E005'

Process was killed due to out of memory condition.

EXECUTION_STALE class-attribute instance-attribute 
EXECUTION_STALE = 'E006'

Execution killed by stale detection — no output for too long.

EXECUTION_UNKNOWN class-attribute instance-attribute 
EXECUTION_UNKNOWN = 'E009'

Unknown execution error with non-zero exit code.

RATE_LIMIT_API class-attribute instance-attribute 
RATE_LIMIT_API = 'E101'

API rate limit exceeded (429, quota, throttling).

RATE_LIMIT_CLI class-attribute instance-attribute 
RATE_LIMIT_CLI = 'E102'

CLI-level rate limiting detected.

CAPACITY_EXCEEDED class-attribute instance-attribute 
CAPACITY_EXCEEDED = 'E103'

Service capacity exceeded (overloaded, try again later).

QUOTA_EXHAUSTED class-attribute instance-attribute 
QUOTA_EXHAUSTED = 'E104'

Token/usage quota exhausted - wait until reset time.

VALIDATION_FILE_MISSING class-attribute instance-attribute 
VALIDATION_FILE_MISSING = 'E201'

Expected output file does not exist.

VALIDATION_CONTENT_MISMATCH class-attribute instance-attribute 
VALIDATION_CONTENT_MISMATCH = 'E202'

Output content does not match expected pattern.

VALIDATION_COMMAND_FAILED class-attribute instance-attribute 
VALIDATION_COMMAND_FAILED = 'E203'

Validation command returned non-zero exit code.

VALIDATION_TIMEOUT class-attribute instance-attribute 
VALIDATION_TIMEOUT = 'E204'

Validation check timed out.

VALIDATION_GENERIC class-attribute instance-attribute 
VALIDATION_GENERIC = 'E209'

Generic validation failure (output validation needed).

CONFIG_INVALID class-attribute instance-attribute 
CONFIG_INVALID = 'E301'

Configuration file is malformed or invalid.

CONFIG_MISSING_FIELD class-attribute instance-attribute 
CONFIG_MISSING_FIELD = 'E302'

Required configuration field is missing.

CONFIG_PATH_NOT_FOUND class-attribute instance-attribute 
CONFIG_PATH_NOT_FOUND = 'E303'

Configuration file path does not exist.

CONFIG_PARSE_ERROR class-attribute instance-attribute 
CONFIG_PARSE_ERROR = 'E304'

Failed to parse configuration file (YAML/JSON syntax error).

CONFIG_MCP_ERROR class-attribute instance-attribute 
CONFIG_MCP_ERROR = 'E305'

MCP server/plugin configuration error (missing env vars, invalid config).

CONFIG_CLI_MODE_ERROR class-attribute instance-attribute 
CONFIG_CLI_MODE_ERROR = 'E306'

Claude CLI mode mismatch (e.g., streaming mode incompatible with operation).

STATE_CORRUPTION class-attribute instance-attribute 
STATE_CORRUPTION = 'E401'

Checkpoint state file is corrupted or inconsistent.

STATE_LOAD_FAILED class-attribute instance-attribute 
STATE_LOAD_FAILED = 'E402'

Failed to load checkpoint state from storage.

STATE_SAVE_FAILED class-attribute instance-attribute 
STATE_SAVE_FAILED = 'E403'

Failed to save checkpoint state to storage.

STATE_VERSION_MISMATCH class-attribute instance-attribute 
STATE_VERSION_MISMATCH = 'E404'

Checkpoint state version is incompatible.

BACKEND_CONNECTION class-attribute instance-attribute 
BACKEND_CONNECTION = 'E501'

Failed to connect to backend service.

BACKEND_AUTH class-attribute instance-attribute 
BACKEND_AUTH = 'E502'

Backend authentication or authorization failed.

BACKEND_RESPONSE class-attribute instance-attribute 
BACKEND_RESPONSE = 'E503'

Invalid or unexpected response from backend.

BACKEND_TIMEOUT class-attribute instance-attribute 
BACKEND_TIMEOUT = 'E504'

Backend request timed out.

BACKEND_NOT_FOUND class-attribute instance-attribute 
BACKEND_NOT_FOUND = 'E505'

Backend executable or service not found.

PREFLIGHT_PATH_MISSING class-attribute instance-attribute 
PREFLIGHT_PATH_MISSING = 'E601'

Required path does not exist (working_dir, referenced file).

PREFLIGHT_PROMPT_TOO_LARGE class-attribute instance-attribute 
PREFLIGHT_PROMPT_TOO_LARGE = 'E602'

Prompt exceeds recommended token limit.

PREFLIGHT_WORKING_DIR_INVALID class-attribute instance-attribute 
PREFLIGHT_WORKING_DIR_INVALID = 'E603'

Working directory is not accessible or not a directory.

PREFLIGHT_VALIDATION_SETUP class-attribute instance-attribute 
PREFLIGHT_VALIDATION_SETUP = 'E604'

Validation target path or pattern is invalid.

NETWORK_CONNECTION_FAILED class-attribute instance-attribute 
NETWORK_CONNECTION_FAILED = 'E901'

Network connection failed (refused, reset, unreachable).

NETWORK_DNS_ERROR class-attribute instance-attribute 
NETWORK_DNS_ERROR = 'E902'

DNS resolution failed.

NETWORK_SSL_ERROR class-attribute instance-attribute 
NETWORK_SSL_ERROR = 'E903'

SSL/TLS handshake or certificate error.

NETWORK_TIMEOUT class-attribute instance-attribute 
NETWORK_TIMEOUT = 'E904'

Network operation timed out.

UNKNOWN class-attribute instance-attribute 
UNKNOWN = 'E999'

Unclassified error - requires investigation.

category property 
category

Get the category prefix (first digit) of this error code.

Returns:

Type Description
str

Category string like "execution", "rate_limit", "validation", etc.
is_retriable property 
is_retriable

Check if this error code is generally retriable.

Returns:

Type Description
bool

True if errors with this code are typically retriable.
Functions
get_retry_behavior 
get_retry_behavior()

Get precise retry behavior for this error code.

Returns error-code-specific delay and retry recommendations. Uses module-level _RETRY_BEHAVIORS constant to avoid rebuilding the lookup table on every call.

Returns:

Type Description
RetryBehavior

RetryBehavior with delay, retriability, and reason.
Source code in src/marianne/core/errors/codes.py 
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
def get_retry_behavior(self) -> RetryBehavior:
    """Get precise retry behavior for this error code.

    Returns error-code-specific delay and retry recommendations.
    Uses module-level _RETRY_BEHAVIORS constant to avoid rebuilding
    the lookup table on every call.

    Returns:
        RetryBehavior with delay, retriability, and reason.
    """
    return _RETRY_BEHAVIORS.get(
        self,
        RetryBehavior(
            delay_seconds=30.0,
            is_retriable=self.is_retriable,
            reason=f"Default behavior for {self.value}",
        ),
    )
get_severity 
get_severity()

Get the severity level for this error code.

Severity assignments: - CRITICAL: Fatal errors requiring immediate attention - ERROR: Most error codes (default) - WARNING: Degraded but potentially temporary conditions - INFO: Reserved for future diagnostic codes

Returns:

Type Description
Severity

Severity level for this error code.
Source code in src/marianne/core/errors/codes.py 
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
def get_severity(self) -> Severity:
    """Get the severity level for this error code.

    Severity assignments:
    - CRITICAL: Fatal errors requiring immediate attention
    - ERROR: Most error codes (default)
    - WARNING: Degraded but potentially temporary conditions
    - INFO: Reserved for future diagnostic codes

    Returns:
        Severity level for this error code.
    """
    # Critical errors - job cannot continue
    critical_codes = {
        ErrorCode.EXECUTION_CRASHED,
        ErrorCode.EXECUTION_OOM,
        ErrorCode.STATE_CORRUPTION,
        ErrorCode.BACKEND_AUTH,
        ErrorCode.BACKEND_NOT_FOUND,
    }
    if self in critical_codes:
        return Severity.CRITICAL

    # Warning level - degraded but potentially temporary
    warning_codes = {
        ErrorCode.CAPACITY_EXCEEDED,
        ErrorCode.VALIDATION_TIMEOUT,
        ErrorCode.EXECUTION_STALE,
    }
    if self in warning_codes:
        return Severity.WARNING

    # Default to ERROR for most codes
    return Severity.ERROR

ErrorCategory

Bases: str, Enum

Categories of errors with different retry behaviors.

Attributes
RATE_LIMIT class-attribute instance-attribute 
RATE_LIMIT = 'rate_limit'

Retriable with long wait - API/service is rate limiting.

TRANSIENT class-attribute instance-attribute 
TRANSIENT = 'transient'

Retriable with backoff - temporary network/service issues.

VALIDATION class-attribute instance-attribute 
VALIDATION = 'validation'

Retriable - Claude ran but didn't produce expected output.

AUTH class-attribute instance-attribute 
AUTH = 'auth'

Fatal - authentication/authorization failure, needs user intervention.

NETWORK class-attribute instance-attribute 
NETWORK = 'network'

Retriable with backoff - network connectivity issues.

TIMEOUT class-attribute instance-attribute 
TIMEOUT = 'timeout'

Retriable - operation timed out.

SIGNAL class-attribute instance-attribute 
SIGNAL = 'signal'

Process killed by signal - may be retriable depending on signal.

FATAL class-attribute instance-attribute 
FATAL = 'fatal'

Non-retriable - stop job immediately.

CONFIGURATION class-attribute instance-attribute 
CONFIGURATION = 'configuration'

Non-retriable - configuration error needs user intervention (e.g., MCP setup).

PREFLIGHT class-attribute instance-attribute 
PREFLIGHT = 'preflight'

Pre-execution check failure — config or environment not ready.

ESCALATION class-attribute instance-attribute 
ESCALATION = 'escalation'

Escalation-based abort — grounding or escalation policy triggered.