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)

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)

Create 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)

Create an APIErrorArgs instance.

Create 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.FormatNotAvailableError(requested_format, available_formats, document=None)

Bases: ValueError

Raised when a requested document format is not available.

This exception is raised when attempting to download a document in a format that is not available for that specific document. It provides programmatic access to the requested format and available alternatives.

requested_format

The format that was requested (e.g., “XML”, “PDF”)

available_formats

List of available format identifiers

document

Optional Document object for additional context

__init__(requested_format, available_formats, document=None)

Initialize FormatNotAvailableError.

Parameters:

• requested_format (str) – The format that was requested

• available_formats (list[str]) – List of available format identifiers

• document (Document | None) – Optional Document object for additional context

exception pyUSPTO.exceptions.USPTOApiAuthError(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)

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)

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)

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)

Initialize a USPTOApiError.

Parameters:

• message (str) – The primary message for the exception (often client-generated context).

• status_code (int | None) – The HTTP status code from the API response (e.g., 400, 403).

• api_short_error (str | None) – The short error description from the API (e.g., “Bad Request”, “Forbidden”).

• error_details (str | dict | None) – The detailed error message or structure from the API.

• request_identifier (str | None) – The request identifier from the API response, if available.

__str__()

Provide 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)

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)

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)

Bases: USPTOApiError

Rate limit exceeded error (HTTP 429).

exception pyUSPTO.exceptions.USPTOApiResponseParseError(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)

Bases: USPTOApiError

Failed to parse response from USPTO API.

This exception is raised when the API returns a 2xx status code but the response body cannot be parsed as JSON. This typically indicates the API returned HTML error pages or other non-JSON content.

exception pyUSPTO.exceptions.USPTOApiServerError(message, status_code=None, api_short_error=None, error_details=None, request_identifier=None)

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)

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)

Bases: USPTOApiError

Request to USPTO API timed out.

pyUSPTO.exceptions.get_api_exception(error_args)

Determine and instantiate 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.