---
title: "ADR-022: Dedicated OAuth exception"
manual: "nr-vault"
version: "1.0"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-vault:adr-022-dedicated-oauth-exception@1.0"
source: "Developer/Adr/ADR-022-DedicatedOAuthException.rst"
rendered: "2026-09-18T07:37:50+00:00"
---

# ADR-022: Dedicated OAuth exception {#adr-022-dedicated-oauth-exception-1}

**Table of contents**

-   [Status](https://docs.typo3.org/permalink/netresearch/nr-vault:status@1.0)
-   [Date](https://docs.typo3.org/permalink/netresearch/nr-vault:date@1.0)
-   [Context](https://docs.typo3.org/permalink/netresearch/nr-vault:context@1.0)
-   [Decision](https://docs.typo3.org/permalink/netresearch/nr-vault:decision@1.0)
-   [Consequences](https://docs.typo3.org/permalink/netresearch/nr-vault:consequences@1.0)
-   [Related decisions](https://docs.typo3.org/permalink/netresearch/nr-vault:related-decisions@1.0)

## Status {#status}

Accepted

## Date {#date}

2026-03-28

## Context {#context}

OAuth-related errors (token refresh failures, invalid grants, expired
tokens, provider errors) used the generic `VaultException` class. This
prevented callers from distinguishing OAuth failures from other vault
errors, making targeted error handling impossible.

For example, a caller wanting to retry on token expiry but fail fast on
a missing secret had to inspect exception messages rather than catching
a specific exception type. This is fragile and violates the principle of
using the type system for error classification.

## Decision {#decision}

Create an `OAuthException` class that extends `VaultException` with
OAuth-specific factory methods:

-   `OAuthException::tokenRefreshFailed(string $provider, string $reason)`
-   `OAuthException::invalidGrant(string $provider)`
-   `OAuthException::providerUnavailable(string $provider)`
-   `OAuthException::tokenExpired(string $provider)`

Each factory method sets an appropriate error code and message, providing
structured error information without exposing sensitive token data.

## Consequences {#consequences}

### Positive {#positive}

-   **Targeted error handling**: Callers can `catch (OAuthException $e)`
    to handle OAuth failures distinctly from other vault errors.
-   **Backward compatible**: `OAuthException` extends `VaultException`,
    so existing `catch (VaultException $e)` blocks continue to work.
-   **Structured errors**: Factory methods ensure consistent error messages
    and codes across all OAuth failure paths.
-   **Type safety**: Error classification moves from string inspection to
    the type system.

### Negative {#negative}

-   **Exception hierarchy growth**: Adding more exception subclasses
    increases the API surface that callers must be aware of.

## Related decisions {#related-decisions}

-   [ADR-008: HTTP client](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-008-http-client@1.0) \- HTTP client integration
-   [ADR-012: SecureHttpClient API and transports](https://docs.typo3.org/permalink/netresearch/nr-vault:adr-012-secure-http-transports@1.0) \- Secure HTTP client transports