Exceptions — pyUSPTO 0.2.3.dev1+g2c5d89b38.d20251125 documentation

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

    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)

    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)

  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)

    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__()

    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)

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

  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.