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.

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

Bases: GlobusError, ValueError

A ValidationError may be raised when the SDK is instructed to handle or parse data which can be seen to be invalid without an external service interaction.

These errors typically do not indicate a usage error similar to GlobusSDKUsageError, but rather that the data is invalid.

class globus_sdk.GlobusAPIError(r, *args, **kwargs)

Bases: GlobusError

Wraps errors returned by a REST API.

Variables:

• http_status (int) – HTTP status code

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

• request_id (str) – The ‘request_id’ included in the error data, if any.

• messages (list[str]) – A list of error messages, extracted from the response data. If the data cannot be parsed or does not contain any clear message fields, this list may be empty.

• errors (list[GlobusSubError]) – A list of sub-error documents, as would be presented by JSON:API APIs and similar interfaces.

property binary_content: bytes

The error message received from a Globus API in bytes.

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 message: str | None

An error message from the API.

If there are multiple messages available, this will contain all messages joined with semicolons. If there is no message available, this will be None.

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

Deprecated alias of the text property.

property text: str

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

class globus_sdk.NetworkError(msg, exc, *args, **kwargs)

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, exc, *args, **kwargs)

Bases: NetworkError

A connection error occurred while making a REST request.

class globus_sdk.GlobusTimeoutError(msg, exc, *args, **kwargs)

Bases: NetworkError

The REST request timed out.

class globus_sdk.GlobusConnectionTimeoutError(msg, exc, *args, **kwargs)

Bases: GlobusTimeoutError

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

ErrorSubdocuments

Errors returned from APIs may define a series of subdocuments, each containing an error object. This is used if there were multiple errors encountered and the API wants to send them back all at once.

All instances of GlobusAPIError define an attribute, errors, which is an array of ErrorSubdocuments.

Error handling code can inspect these sub-errors like so:

try:
    some_complex_globus_operation()
except GlobusAPIError as e:
    if e.errors:
        print("sub-errors encountered")
        print("(code, message)")
        for suberror in e.errors:
            print(f"({suberror.code}, {suberror.message}")

class globus_sdk.exc.ErrorSubdocument(data, *, message_fields=None)

Error subdocuments as returned by Globus APIs.

Variables:

raw (dict) – The unparsed error subdocument

property code: str | None

The ‘code’ string of this subdocument, derived from its data based on the parsing context.

May be None if no code is defined.

get(key, default=None)

A dict-like getter for the raw data.

Parameters:

• key (str) – The string key to use for lookup

• default (Any) – The default value to use

Return type:

Any | None

property message: str | None

The ‘message’ string of this subdocument, derived from its data based on the parsing context.

May be None if no message is defined.

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)

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)

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)

• session_required_policies (list of str, optional) – A list of policies required for the session.

• session_required_mfa (bool, optional) – Whether MFA is required for the session.

Examples

>>> try:
>>>     ...  # something
>>> except GlobusAPIError as err:
>>>     # get a parsed AuthorizationParameterInfo 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)

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