Errors

Custom exceptions for notion-sdk-py.

This module defines the exceptions that can be raised when an error occurs.

APIErrorCode

Bases: str, Enum

Error codes returned in responses from the API.

Source code in notion_client/errors.py

class APIErrorCode(str, Enum):
    """Error codes returned in responses from the API."""

    Unauthorized = "unauthorized"
    """The bearer token is not valid."""

    RestrictedResource = "restricted_resource"
    """Given the bearer token used, the client doesn't have permission to
    perform this operation."""

    ObjectNotFound = "object_not_found"
    """Given the bearer token used, the resource does not exist.
    This error can also indicate that the resource has not been shared with owner
    of the bearer token."""

    RateLimited = "rate_limited"
    """This request exceeds the number of requests allowed. Slow down and try again."""

    InvalidJSON = "invalid_json"
    """The request body could not be decoded as JSON."""

    InvalidRequestURL = "invalid_request_url"
    """The request URL is not valid."""

    InvalidRequest = "invalid_request"
    """This request is not supported."""

    InvalidBeta = "invalid_beta"
    """The `Notion-Beta` header is malformed, unknown, duplicated, or references a
    stale revision."""

    ValidationError = "validation_error"
    """The request body does not match the schema for the expected parameters."""

    ConflictError = "conflict_error"
    """The transaction could not be completed, potentially due to a data collision.
    Make sure the parameters are up to date and try again."""

    InternalServerError = "internal_server_error"
    """An unexpected error occurred. Reach out to Notion support."""

    ServiceOverload = "service_overload"
    """Notion is overloaded. Slow down and try again later."""

    ServiceUnavailable = "service_unavailable"
    """Notion is unavailable. Try again later.
    This can occur when the time to respond to a request takes longer than 60 seconds,
    the maximum request timeout."""

    GatewayTimeout = "gateway_timeout"
    """The request timed out on the server side."""

ConflictError = 'conflict_error' class-attribute instance-attribute

The transaction could not be completed, potentially due to a data collision. Make sure the parameters are up to date and try again.

GatewayTimeout = 'gateway_timeout' class-attribute instance-attribute

The request timed out on the server side.

InternalServerError = 'internal_server_error' class-attribute instance-attribute

An unexpected error occurred. Reach out to Notion support.

InvalidBeta = 'invalid_beta' class-attribute instance-attribute

The Notion-Beta header is malformed, unknown, duplicated, or references a stale revision.

InvalidJSON = 'invalid_json' class-attribute instance-attribute

The request body could not be decoded as JSON.

InvalidRequest = 'invalid_request' class-attribute instance-attribute

This request is not supported.

InvalidRequestURL = 'invalid_request_url' class-attribute instance-attribute

The request URL is not valid.

ObjectNotFound = 'object_not_found' class-attribute instance-attribute

Given the bearer token used, the resource does not exist. This error can also indicate that the resource has not been shared with owner of the bearer token.

RateLimited = 'rate_limited' class-attribute instance-attribute

This request exceeds the number of requests allowed. Slow down and try again.

RestrictedResource = 'restricted_resource' class-attribute instance-attribute

Given the bearer token used, the client doesn't have permission to perform this operation.

ServiceOverload = 'service_overload' class-attribute instance-attribute

Notion is overloaded. Slow down and try again later.

ServiceUnavailable = 'service_unavailable' class-attribute instance-attribute

Notion is unavailable. Try again later. This can occur when the time to respond to a request takes longer than 60 seconds, the maximum request timeout.

Unauthorized = 'unauthorized' class-attribute instance-attribute

The bearer token is not valid.

ValidationError = 'validation_error' class-attribute instance-attribute

The request body does not match the schema for the expected parameters.

ClientErrorCode

Bases: str, Enum

Error codes generated for client errors.

Source code in notion_client/errors.py

class ClientErrorCode(str, Enum):
    """Error codes generated for client errors."""

    RequestTimeout = "notionhq_client_request_timeout"
    ResponseError = "notionhq_client_response_error"
    InvalidPathParameter = "notionhq_client_invalid_path_parameter"

InvalidPathParameterError

Bases: NotionClientErrorBase

Error thrown when a path parameter contains invalid characters such as path traversal sequences (..) that could alter the intended API endpoint.

Source code in notion_client/errors.py

class InvalidPathParameterError(NotionClientErrorBase):
    """Error thrown when a path parameter contains invalid characters such as
    path traversal sequences (..) that could alter the intended API endpoint."""

    code: ClientErrorCode = ClientErrorCode.InvalidPathParameter

    def __init__(
        self,
        message: str = (
            "Path parameter contains invalid characters that could alter the request path"
        ),
    ) -> None:
        super().__init__(message)

    @staticmethod
    def is_invalid_path_parameter_error(error: object) -> bool:
        return _is_notion_client_error_with_code(
            error,
            {ClientErrorCode.InvalidPathParameter.value},
        )

NotionClientErrorBase

Bases: Exception

Base error type for all Notion client errors.

Source code in notion_client/errors.py

class NotionClientErrorBase(Exception):
    """Base error type for all Notion client errors."""

    code: Union[str, NotionErrorCode]

    def __init__(self, message: str = "") -> None:
        super().__init__(message)

RequestTimeoutError

Bases: NotionClientErrorBase

Error thrown by the client if a request times out.

Source code in notion_client/errors.py

class RequestTimeoutError(NotionClientErrorBase):
    """Error thrown by the client if a request times out."""

    code: ClientErrorCode = ClientErrorCode.RequestTimeout

    def __init__(self, message: str = "Request to Notion API has timed out") -> None:
        super().__init__(message)

    @staticmethod
    def is_request_timeout_error(error: Any) -> bool:
        return _is_notion_client_error_with_code(
            error,
            {ClientErrorCode.RequestTimeout.value},
        )

    @staticmethod
    async def reject_after_timeout(coro: Any, timeout_ms: int) -> Any:
        try:
            return await asyncio.wait_for(coro, timeout=timeout_ms / 1000.0)
        except asyncio.TimeoutError:
            raise RequestTimeoutError()

UnknownHTTPResponseError

Bases: HTTPResponseError

Error thrown if an API call responds with an unknown error code, or does not respond with a properly-formatted error.

Source code in notion_client/errors.py

class UnknownHTTPResponseError(HTTPResponseError):
    """Error thrown if an API call responds with an unknown error code, or does not respond with
    a properly-formatted error.
    """

    def __init__(
        self,
        status: int,
        message: Optional[str] = None,
        headers: Optional[httpx.Headers] = None,
        raw_body_text: str = "",
    ) -> None:
        if headers is None:
            headers = httpx.Headers()
        if message is None:
            message = _build_unknown_response_message(status, headers)

        super().__init__(
            code=ClientErrorCode.ResponseError.value,
            status=status,
            message=message,
            headers=headers,
            raw_body_text=raw_body_text,
            additional_data=None,
        )

    @staticmethod
    def is_unknown_http_response_error(error: Any) -> bool:
        return _is_notion_client_error_with_code(
            error,
            {ClientErrorCode.ResponseError.value},
        )

validate_request_path(path)

Validates that a request path does not contain path traversal sequences. Raises InvalidPathParameterError if the path contains ".." segments, including URL-encoded variants like %2e%2e.

Source code in notion_client/errors.py

def validate_request_path(path: str) -> None:
    """Validates that a request path does not contain path traversal sequences.
    Raises InvalidPathParameterError if the path contains ".." segments,
    including URL-encoded variants like %2e%2e."""

    # Check for literal path traversal
    if ".." in path:
        raise InvalidPathParameterError(
            f'Request path "{path}" contains path traversal sequence ".."'
        )

    # Check for URL-encoded path traversal (%2e = '.')
    # Only decode if path contains potential encoded dots
    if "%2e" in path.lower():
        decoded = unquote(path)
        if ".." in decoded:
            raise InvalidPathParameterError(
                f'Request path "{path}" contains encoded path traversal sequence'
            )