Exceptions

exceptions - Exception classes for USPTO API clients

This module provides exception classes for USPTO API errors that correspond to the various response types from the USPTO API. It also includes helper structures and functions for creating these exceptions.

class pyUSPTO.exceptions.APIErrorArgs(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)[source]

Bases: object

Data structure to hold arguments for API exception constructors.

api_short_error: str | None = None

error_details: str | dict | None = None

classmethod from_http_error(http_error, client_operation_message)[source]

Creates an APIErrorArgs instance by parsing a requests.exceptions.HTTPError.

Parameters:

http_error (HTTPError) – The HTTPError object from the requests library.
client_operation_message (str) – A message describing the client operation that failed.

Return type:

APIErrorArgs

Returns:

An instance of APIErrorArgs populated with details from the HTTPError.

classmethod from_request_exception(request_exception, client_operation_message=None)[source]

Creates an APIErrorArgs instance from a generic requests.exceptions.RequestException (e.g., ConnectionError, Timeout) that is not an HTTPError.

Return type:: APIErrorArgs

message: str

request_identifier: str | None = None

status_code: int | None = None

exception pyUSPTO.exceptions.USPTOApiAuthError(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)[source]

Bases: USPTOApiError

Authentication/Authorization error (HTTP 401/403).

exception pyUSPTO.exceptions.USPTOApiBadRequestError(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)[source]

Bases: USPTOApiError

Bad Request error (HTTP 400).

exception pyUSPTO.exceptions.USPTOApiError(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)[source]

Bases: Exception

Base exception for USPTO API errors. This is the parent class for all USPTO API-specific exceptions. It includes information about the status code, API’s short error message, detailed error information, and request identifier from the API response.

DEFAULT_UNKNOWN_MESSAGE = 'UNK USPTO API ERROR'

__init__(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)[source]: Initializes the USPTOApiError. :type message: str :param message: The primary message for the exception (often client-generated context). :type status_code: int | None :param status_code: The HTTP status code from the API response (e.g., 400, 403). :type api_short_error: str | None :param api_short_error: The short error description from the API (e.g., “Bad Request”, “Forbidden”). :type error_details: str | dict | None :param error_details: The detailed error message or structure from the API. :type request_identifier: str | None :param request_identifier: The request identifier from the API response, if available.

__str__()[source]

Provides a more informative string representation of the error.

Return type:: str

property message: str: Provides direct access to the primary exception message. This refers to the first argument passed to the exception, which is conventionally the main human-readable message.

exception pyUSPTO.exceptions.USPTOApiNotFoundError(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)[source]

Bases: USPTOApiError

Resource not found error (HTTP 404).

exception pyUSPTO.exceptions.USPTOApiPayloadTooLargeError(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)[source]

Bases: USPTOApiError

Payload Too Large error (HTTP 413).

exception pyUSPTO.exceptions.USPTOApiRateLimitError(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)[source]

Bases: USPTOApiError

Rate limit exceeded error (HTTP 429).

exception pyUSPTO.exceptions.USPTOApiServerError(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)[source]

Bases: USPTOApiError

Internal Server Error (HTTP 500 series).

exception pyUSPTO.exceptions.USPTOConnectionError(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)[source]

Bases: USPTOApiError

Network-level connection error (DNS failure, refused connection, etc.).

exception pyUSPTO.exceptions.USPTOTimeout(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)[source]

Bases: USPTOApiError

Request to USPTO API timed out.

pyUSPTO.exceptions.get_api_exception(error_args)[source]

Determines and instantiates the appropriate USPTOApiError subclass based on the status code in error_args.

Parameters:: error_args (APIErrorArgs) – An instance of APIErrorArgs containing all necessary information to construct the exception.
Return type:: USPTOApiError
Returns:: An instance of a USPTOApiError subclass.