# Exception hierarchy

All exceptions thrown by the Ratepay SDK extend `RatepayException`, an unchecked `RuntimeException`.

You are not required to catch these exceptions, but you should handle them when your application needs to respond differently to specific errors.

## Exception types

| Exception | Description | Notable fields |
|  --- | --- | --- |
| `RatepayException` | Base class for all SDK exceptions. Not thrown directly. | `message`, `cause` |
| `RatepaySdkValidationException` | A request fails a local pre-flight check before any HTTP call (currently only `authorize`). | — |
| `RatepayConfigurationException` | Missing or invalid client credentials or environment configuration during initialization. | — |
| `RatepayAuthException` | OAuth authentication failure, typically during initial authentication or token renewal. | `error`, `errorDescription`, `statusCode` |
| `RatepayValidationException` | HTTP 400 response with a structured decline payload, typically for capture, cancellation, refund, incremental authorization, or shipping information operations. | `apiError` |
| `RatepayApiException` | Base class for API exceptions associated with specific HTTP errors, such as 404. | `apiError` |
| `RatepayNotFoundException` | HTTP 404 response when no more specific exception applies. | `apiError` |
| `RatepayTransactionNotFoundException` | Transaction not found (HTTP 404). Related exceptions include `RatepayAuthorizationNotFoundException`, `RatepayCaptureNotFoundException`, `RatepayCancellationNotFoundException`, and `RatepayRefundNotFoundException`. | `apiError` |
| `RatepayLegalException` | Request rejected for legal reasons (HTTP 451). | `apiError` |
| `RatepayOtpException` | OTP-specific error during verification or regeneration. | `otpError` |
| `RatepayNetworkException` | Network or transport failure (such as a timeout or connection error), or an HTTP 5xx response. | `retryable` (always `true`) |


## Handling an API error

Exceptions such as `RatepayValidationException`, `RatepayTransactionNotFoundException`, and `RatepayLegalException` may contain an `apiError` object with structured error details.

You can inspect the decline category and reasons to determine how your application should handle the error.


```java Java
catch (RatepayValidationException e) {
    RatepayApiError apiError = e.getApiError();
    if (apiError != null) {
        DeclineCategory category = apiError.getDecline().getCategory();
        List<DeclineReason> reasons = apiError.getDecline().getReasons();
    }
}
```


```kotlin Kotlin
catch (e: RatepayValidationException) {
    e.apiError?.decline?.let { decline ->
        val category = decline.category
        val reasons = decline.reasons
    }
}
```

### Handling unknown decline values

The API may introduce new `DeclineCategory` or `DeclineReason` values before the SDK is updated.

Unrecognized values are mapped to `UNKNOWN` rather than causing deserialization to fail.

Ensure your application handles `UNKNOWN` values gracefully, for example, by logging the unexpected value and applying a fallback error-handling path.

## Next

See [Idempotency and retries](/docs/developer/sdk/errors-and-resilience/idempotency-and-retries) to learn how to safely retry failed operations.