Exceptions

All Globus SDK errors inherit from GlobusError, and all SDK error classes are importable from globus_sdk.

You can therefore capture all errors thrown by the SDK by looking for GlobusError, as in

import logging
from globus_sdk import TransferClient, GlobusError

try:
    tc = TransferClient(...)
    # search with no parameters will throw an exception
    eps = tc.endpoint_search()
except GlobusError:
    logging.exception("Globus Error!")
    raise

In most cases, it’s best to look for specific subclasses of GlobusError. For example, to write code which is distinguishes between network failures and unexpected API conditions, you’ll want to look for NetworkError and GlobusAPIError

import logging
from globus_sdk import TransferClient, GlobusError, GlobusAPIError, NetworkError

try:
    tc = TransferClient(...)

    eps = tc.endpoint_search(filter_fulltext="myendpointsearch")

    for ep in eps:
        print(ep["display_name"])

    ...
except GlobusAPIError as e:
    # Error response from the REST service, check the code and message for
    # details.
    logging.error(
        "Got a Globus API Error\n"
        f"Error Code: {e.code}\n"
        f"Error Message: {e.message}"
    )
    raise e
except NetworkError:
    logging.error("Network Failure. Possibly a firewall or connectivity issue")
    raise
except GlobusError:
    logging.exception("Totally unexpected GlobusError!")
    raise
else:
    ...

Of course, if you want to learn more information about the response, you should inspect it more than this.

All errors raised by the SDK should be instances of GlobusError. Malformed calls to Globus SDK methods typically raise GlobusSDKUsageError, but, in rare cases, may raise standard python exceptions (ValueError, OSError, etc.)

Error Classes

class globus_sdk.GlobusError

Bases: Exception

Root of the Globus Exception hierarchy. Stub class.

class globus_sdk.GlobusSDKUsageError

Bases: GlobusError, ValueError

A GlobusSDKUsageError may be thrown in cases in which the SDK detects that it is being used improperly.

These errors typically indicate that some contract regarding SDK usage (e.g. required order of operations) has been violated.

class globus_sdk.GlobusAPIError(r: Response, *args: Any, **kwargs: Any)

Bases: GlobusError

Wraps errors returned by a REST API.

Variables:

• http_status – HTTP status code (int)

• code – Error code from the API (str), or “Error” for unclassified errors

• message – Error message from the API. In general, this will be more useful to developers, but there may be cases where it’s suitable for display to end users.

property headers: Mapping[str, str]

The HTTP response headers as a case-insensitive mapping.

For example, headers["Content-Length"] and headers["content-length"] are treated as equivalent.

property http_reason: str

The HTTP reason string from the response.

This is the part of the status line after the status code, and typically is a string description of the status. If the status line is HTTP/1.1 404 Not Found, then this is the string "Not Found".

property info: ErrorInfoContainer

An ErrorInfoContainer with parsed error data. The info of an error is guaranteed to be present, but all of its contents may be falsey if the error could not be parsed.

property raw_json: dict[str, Any] | None

Get the verbatim error message received from a Globus API, interpreted as JSON data

If the body cannot be loaded as JSON, this is None

property raw_text: str

Get the verbatim error message received from a Globus API as a string

class globus_sdk.NetworkError(msg: str, exc: Exception, *args: Any, **kwargs: Any)

Bases: GlobusError

Error communicating with the REST API server.

Holds onto original exception data, but also takes a message to explain potentially confusing or inconsistent exceptions passed to us

class globus_sdk.GlobusConnectionError(msg: str, exc: Exception, *args: Any, **kwargs: Any)

Bases: NetworkError

A connection error occured while making a REST request.

class globus_sdk.GlobusTimeoutError(msg: str, exc: Exception, *args: Any, **kwargs: Any)

Bases: NetworkError

The REST request timed out.

class globus_sdk.GlobusConnectionTimeoutError(msg: str, exc: Exception, *args: Any, **kwargs: Any)

Bases: GlobusTimeoutError

The request timed out during connection establishment. These errors are safe to retry.

ErrorInfo

GlobusAPIError and its subclasses all support an info property which may contain parsed error data. The info is guaranteed to be there, but its attributes should be tested before use, as in

# if 'err' is an API error, then 'err.info' is an 'ErrorInfoContainer',
# a wrapper which holds ErrorInfo objects
# 'err.info.consent_required' is a 'ConsentRequiredInfo', which should be
# tested for truthy/falsey-ness before use
if err.info.consent_required:
    print(
        "Got a ConsentRequired error with scopes:",
        err.info.consent_required.required_scopes,
    )

class globus_sdk.exc.ErrorInfoContainer(error_data: dict[str, Any] | None)

This is a wrapper type which contains various error info objects for parsed error data. It is attached to API errors as the .info attribute.

Variables:

• authorization_parameters – A parsed AuthorizationParameterInfo object

• consent_required – A parsed ConsentRequiredInfo object

class globus_sdk.exc.ErrorInfo

Errors may contain “containers” of data which are testable (define __bool__). When they have data, they should bool() as True

class globus_sdk.exc.AuthorizationParameterInfo(error_data: dict[str, Any])

Bases: ErrorInfo

AuthorizationParameterInfo objects may contain information about the ‘authorization_parameters’ of an error. They test as truthy when the error has valid ‘authorization_parameters’ data.

Variables:

• session_message (str, optional) – A message from the server

• session_required_identities (list of str, optional) – A list of identity IDs as strings which are being requested by the server

• session_required_single_domain (list of str, optional) – A list of domains which are being requested by the server (“single domain” because the user should choose one)

Examples

>>> try:
>>>     ...  # something
>>> except GlobusAPIError as err:
>>>     # get a parsed AuthorizationParamaterInfo object, and check if it's truthy
>>>     authz_params = err.info.authorization_parameters
>>>     if not authz_params:
>>>         raise
>>>     # whatever handling code is desired...
>>>     print("got authz params:", authz_params)

class globus_sdk.exc.ConsentRequiredInfo(error_data: dict[str, Any])

Bases: ErrorInfo

ConsentRequiredInfo objects contain required consent information for an error. They test as truthy if the error was marked as a ConsentRequired error.

Variables:

required_scopes (list of str, optional) – A list of scopes requested by the server