Implementation:Apache Paimon RestException

Knowledge Sources	Apache_Paimon
Domains	Error Handling, REST API
Last Updated	2026-02-08 00:00 GMT

Overview

RestException provides a hierarchy of HTTP-specific exception classes for handling REST API errors in Apache Paimon with proper status code mapping and error context.

Description

The RestException module defines a comprehensive exception hierarchy for REST API error handling. The base RESTException class extends Python's Exception with additional features like cause tracking, stack trace printing, and formatted message support with variable substitution. It preserves exception chaining through the __cause__ attribute for better debugging.

The module provides specialized exception classes mapped to standard HTTP status codes: BadRequestException (400), NotAuthorizedException (401), ForbiddenException (403), NoSuchResourceException (404), AlreadyExistsException (409), ServiceFailureException (500), NotImplementedException (501), and ServiceUnavailableException (503). Some exceptions like NoSuchResourceException and AlreadyExistsException include resource context (resource_type and resource_name) to provide detailed error information.

RESTException handles message formatting safely, attempting Python string formatting first and falling back to simple concatenation if formatting fails. It provides utility methods like get_message(), print_stack_trace(), and get_stack_trace() for error inspection and logging. The exception hierarchy enables proper error handling in REST clients by allowing catch blocks to discriminate between different types of API failures.

Usage

Use RestException classes when implementing REST API clients or servers that need standardized error handling, translating HTTP status codes to typed exceptions, or providing detailed error context for debugging API failures.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-python/pypaimon/api/rest_exception.py

Signature

class RESTException(Exception):
    def __init__(self, message: str = None, *args: Any, cause: Optional[Exception] = None):
        pass

    def get_cause(self) -> Optional[Exception]:
        pass

    def get_message(self) -> str:
        pass

    def print_stack_trace(self) -> None:
        pass

    def get_stack_trace(self) -> str:
        pass

class BadRequestException(RESTException):
    def __init__(self, message: str = None, *args: Any):
        pass

class NotAuthorizedException(RESTException):
    """Exception for not authorized (401)"""
    def __init__(self, message: str, *args: Any):
        pass

class ForbiddenException(RESTException):
    """Exception for forbidden access (403)"""
    def __init__(self, message: str, *args: Any):
        pass

class NoSuchResourceException(RESTException):
    """Exception for resource not found (404)"""
    def __init__(self, resource_type: Optional[str], resource_name: Optional[str],
                 message: str, *args: Any):
        pass

class AlreadyExistsException(RESTException):
    """Exception for resource already exists (409)"""
    def __init__(self, resource_type: Optional[str], resource_name: Optional[str],
                 message: str, *args: Any):
        pass

class ServiceFailureException(RESTException):
    """Exception for service failure (500)"""
    def __init__(self, message: str, *args: Any):
        pass

class NotImplementedException(RESTException):
    """Exception for not implemented (501)"""
    def __init__(self, message: str, *args: Any):
        pass

class ServiceUnavailableException(RESTException):
    """Exception for service unavailable (503)"""
    def __init__(self, message: str, *args: Any):
        pass

Import

from pypaimon.api.rest_exception import (
    RESTException, BadRequestException, NotAuthorizedException,
    ForbiddenException, NoSuchResourceException, AlreadyExistsException,
    ServiceFailureException, NotImplementedException, ServiceUnavailableException
)

I/O Contract

Inputs

Name	Type	Required	Description
message	str	No	Error message with optional format placeholders
args	Any	No	Arguments for message formatting
cause	Exception	No	Underlying exception that caused this error
resource_type	str	No	Type of resource (for resource-specific exceptions)
resource_name	str	No	Name of resource (for resource-specific exceptions)

Outputs

Name	Type	Description
exception	RESTException	Raised exception with formatted message and context
stack_trace	str	Formatted stack trace string

Usage Examples

from pypaimon.api.rest_exception import (
    NoSuchResourceException, AlreadyExistsException,
    ServiceFailureException, RESTException
)

# Raise a resource not found exception
try:
    raise NoSuchResourceException(
        resource_type="Table",
        resource_name="my_database.my_table",
        message="The specified table does not exist"
    )
except NoSuchResourceException as e:
    print(f"Error: {e.get_message()}")
    print(f"Resource: {e.resource_type}/{e.resource_name}")

# Raise exception with formatted message
try:
    raise ServiceFailureException(
        "Failed to connect to %s:%d",
        "localhost", 8080
    )
except ServiceFailureException as e:
    print(e)  # "Failed to connect to localhost:8080"

# Chain exceptions with cause
try:
    try:
        # Some operation that fails
        raise ValueError("Connection timeout")
    except ValueError as ve:
        raise RESTException("API call failed", cause=ve)
except RESTException as e:
    print(f"Main error: {e.get_message()}")
    print(f"Caused by: {e.get_cause()}")
    e.print_stack_trace()  # Print full stack trace

# Handle different exception types
try:
    # REST API call
    pass
except NotAuthorizedException:
    print("Authentication required")
except ForbiddenException:
    print("Access denied")
except ServiceUnavailableException:
    print("Service temporarily unavailable")
except RESTException as e:
    print(f"API error: {e}")
    stack = e.get_stack_trace()
    # Log stack trace for debugging

Related Pages

• Principle:Apache_Paimon_REST_Catalog_Protocol