ADR-006: Define Reusable Exception Types Under RpaPub.Devkit.Exceptions Namespace

Status

Proposed

Context

The MaestroTaskProcessTemplate and similar RPA projects require clear and consistent error signaling between the process logic, the global exception handler, and the caller (e.g., UiPath Maestro).

For this purpose, two categories of exceptions must be distinguished:

• Retryable failures (e.g., transient infrastructure errors)
• Non-retryable failures (e.g., business rule violations)

Rather than relying on loosely interpreted framework exceptions (like TimeoutException or BusinessRuleException), we need template-owned, purpose-built exception types that:

• Explicitly convey retryability
• Are readable and intuitive for consuming developers
• Can be reused across RPA templates and helper libraries

Decision

We will define and publish the following exception types under the namespace:

RpaPub.Devkit.Exceptions

✅ Exception Types

• RetryableFailureException
  For recoverable issues like timeouts, service unavailability, etc.

• NonRetryableFailureException
  For unrecoverable logic errors like invalid input, business rule violations, or misconfiguration.

✅ Usage Expectations

• These types will be thrown by consuming developers within the Process.xaml or invoked business logic.
• The GlobalHandler.xaml will classify exceptions strictly based on these two types—no string-based heuristics, retry counts, or guesswork.
• The project will import RpaPub.Devkit.Exceptions into Studio (TextExpression.NamespacesForImplementation) to ensure frictionless developer use.

Rationale

Goal	Solution Alignment
Developer readability	Throw New RetryableFailureException("msg") is expressive and Studio-friendly
Reusability across templates	Namespace is decoupled from specific template (no Template*)
Exception ownership	RpaPub reflects GitHub org and internal package control
Clear orchestration contract	Maestro reads errorType = retryable/nonretryable based on schema
Avoid magic or guesswork	No fuzzy classification based on message content

Consequences

• Developers must learn and adopt the designated exception types.
• GlobalHandler.xaml will only classify these types; all others will default to nonretryable (or optionally log unexpected types).
• Future shared components (e.g., Logging, Diagnostics, Validation) may extend under RpaPub.Devkit.*.

Alternatives Considered

Option	Reason for Rejection
Use built-in exceptions (TimeoutException, BusinessRuleException)	Too implicit; error intent unclear; Studio behavior inconsistent
Use TemplateRetryableException in template namespace	Poor readability; not reusable; tied to a specific project
Use message-based classification in GlobalHandler	Brittle and hard to test; easy to break silently

Related

• ADR-004: Procedural Error Handling and Status Finalization
• GlobalHandler.xaml (refactored)
• GlobalErrorHelpers.cs
• status-schema.v1.json

Owner

Christian Prior-Mamulyan [email protected]