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 | 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) |
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.
catch (RatepayValidationException e) {
RatepayApiError apiError = e.getApiError();
if (apiError != null) {
DeclineCategory category = apiError.getDecline().getCategory();
List<DeclineReason> reasons = apiError.getDecline().getReasons();
}
}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.
See Idempotency and retries to learn how to safely retry failed operations.