Skip to content

Errors

Custom exceptions for notion-sdk-py.

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

APIErrorCode

Bases: str, Enum

Source code in notion_client/errors.py
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
class APIErrorCode(str, Enum):
    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."""

    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."""

    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."""

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.

InternalServerError = 'internal_server_error' class-attribute instance-attribute

An unexpected error occurred. Reach out to Notion support.

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.

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.

APIResponseError

Bases: HTTPResponseError

An error raised by Notion API.

Source code in notion_client/errors.py
89
90
91
92
93
94
95
96
97
98
class APIResponseError(HTTPResponseError):
    """An error raised by Notion API."""

    code: APIErrorCode

    def __init__(
        self, response: httpx.Response, message: str, code: APIErrorCode
    ) -> None:
        super().__init__(response, message)
        self.code = code

HTTPResponseError

Bases: Exception

Exception for HTTP errors.

Responses from the API use HTTP response codes that are used to indicate general classes of success and error.

Source code in notion_client/errors.py
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
class HTTPResponseError(Exception):
    """Exception for HTTP errors.

    Responses from the API use HTTP response codes that are used to indicate general
    classes of success and error.
    """

    code: str = "notionhq_client_response_error"
    status: int
    headers: httpx.Headers
    body: str

    def __init__(self, response: httpx.Response, message: Optional[str] = None) -> None:
        if message is None:
            message = (
                f"Request to Notion API failed with status: {response.status_code}"
            )
        super().__init__(message)
        self.status = response.status_code
        self.headers = response.headers
        self.body = response.text

RequestTimeoutError

Bases: Exception

Exception for requests that timeout.

The request that we made waits for a specified period of time or maximum number of retries to get the response. But if no response comes within the limited time or retries, then this Exception is raised.

Source code in notion_client/errors.py
11
12
13
14
15
16
17
18
19
20
21
22
class RequestTimeoutError(Exception):
    """Exception for requests that timeout.

    The request that we made waits for a specified period of time or maximum number of
    retries to get the response. But if no response comes within the limited time or
    retries, then this Exception is raised.
    """

    code = "notionhq_client_request_timeout"

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

is_api_error_code(code)

Check if given code belongs to the list of valid API error codes.

Source code in notion_client/errors.py
101
102
103
104
105
def is_api_error_code(code: str) -> bool:
    """Check if given code belongs to the list of valid API error codes."""
    if isinstance(code, str):
        return code in (error_code.value for error_code in APIErrorCode)
    return False