{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars/sdk_sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["code-group"]},"type":"markdown"},"seo":{"title":"Exception hierarchy","description":"The specifications of Ratepay's APIs for easy payment transactions.","siteUrl":"https://docs.ratepay.com","keywords":"Ratepay developer portal, Ratepay api portal, Ratepay api reference docs","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"exception-hierarchy","__idx":0},"children":["Exception hierarchy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All exceptions thrown by the Ratepay SDK extend ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayException"]},", an unchecked ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RuntimeException"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You are not required to catch these exceptions, but you should handle them when your application needs to respond differently to specific errors."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"exception-types","__idx":1},"children":["Exception types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Exception"},"children":["Exception"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notable fields"},"children":["Notable fields"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Base class for all SDK exceptions. Not thrown directly."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cause"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepaySdkValidationException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A request fails a local pre-flight check before any HTTP call (currently only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorize"]},")."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayConfigurationException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid client credentials or environment configuration during initialization."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayAuthException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OAuth authentication failure, typically during initial authentication or token renewal."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorDescription"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["statusCode"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayValidationException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP 400 response with a structured decline payload, typically for capture, cancellation, refund, incremental authorization, or shipping information operations."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiError"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayApiException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Base class for API exceptions associated with specific HTTP errors, such as 404."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiError"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayNotFoundException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP 404 response when no more specific exception applies."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiError"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayTransactionNotFoundException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction not found (HTTP 404). Related exceptions include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayAuthorizationNotFoundException"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayCaptureNotFoundException"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayCancellationNotFoundException"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayRefundNotFoundException"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiError"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayLegalException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request rejected for legal reasons (HTTP 451)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiError"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayOtpException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OTP-specific error during verification or regeneration."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["otpError"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayNetworkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Network or transport failure (such as a timeout or connection error), or an HTTP 5xx response."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retryable"]}," (always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-an-api-error","__idx":2},"children":["Handling an API error"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Exceptions such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayValidationException"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayTransactionNotFoundException"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RatepayLegalException"]}," may contain an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiError"]}," object with structured error details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can inspect the decline category and reasons to determine how your application should handle the error."]},{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"tabs"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","data-title":"Java","header":{"title":"Java","controls":{"copy":{}}},"source":"catch (RatepayValidationException e) {\n    RatepayApiError apiError = e.getApiError();\n    if (apiError != null) {\n        DeclineCategory category = apiError.getDecline().getCategory();\n        List<DeclineReason> reasons = apiError.getDecline().getReasons();\n    }\n}\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"kotlin","data-title":"Kotlin","header":{"title":"Kotlin","controls":{"copy":{}}},"source":"catch (e: RatepayValidationException) {\n    e.apiError?.decline?.let { decline ->\n        val category = decline.category\n        val reasons = decline.reasons\n    }\n}\n","lang":"kotlin"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"handling-unknown-decline-values","__idx":3},"children":["Handling unknown decline values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API may introduce new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DeclineCategory"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DeclineReason"]}," values before the SDK is updated."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unrecognized values are mapped to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNKNOWN"]}," rather than causing deserialization to fail."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ensure your application handles ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNKNOWN"]}," values gracefully, for example, by logging the unexpected value and applying a fallback error-handling path."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next","__idx":4},"children":["Next"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/developer/sdk/errors-and-resilience/idempotency-and-retries"},"children":["Idempotency and retries"]}," to learn how to safely retry failed operations."]}]},"headings":[{"value":"Exception hierarchy","id":"exception-hierarchy","depth":1},{"value":"Exception types","id":"exception-types","depth":2},{"value":"Handling an API error","id":"handling-an-api-error","depth":2},{"value":"Handling unknown decline values","id":"handling-unknown-decline-values","depth":3},{"value":"Next","id":"next","depth":2}],"frontmatter":{"seo":{"title":"Exception hierarchy"}},"lastModified":"2026-11-03T16:52:27.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/developer/sdk/errors-and-resilience/exception-hierarchy","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}