Skip to content

Exceptions

All exceptions inherit from MQRESTError.

Exception
└── MQRESTError
    ├── MQRESTAuthError        — authentication failures
    ├── MQRESTTransportError   — network/connection failures
    ├── MQRESTResponseError    — malformed responses
    ├── MQRESTCommandError     — MQSC command failures
    └── MQRESTTimeoutError     — sync operation timeouts

MQRESTError

The base exception class. All library exceptions inherit from this class.

Bases: Exception

Base error for all MQ REST session failures.

All pymqrest exceptions inherit from this class, so except MQRESTError catches every error raised by the library.

Source code in src/pymqrest/exceptions.py 
11
12
13
14
15
16
class MQRESTError(Exception):
    """Base error for all MQ REST session failures.

    All pymqrest exceptions inherit from this class, so
    ``except MQRESTError`` catches every error raised by the library.
    """

MQRESTTransportError

Thrown when the HTTP request fails at the network level — connection refused, DNS resolution failure, TLS handshake error, etc.

from pymqrest.exceptions import MQRESTTransportError

try:
    session.display_queue("MY.QUEUE")
except MQRESTTransportError as err:
    print(f"Cannot reach MQ: {err}")
    print(f"Cause: {err.__cause__}")

Bases: MQRESTError

Raised when the transport fails to reach the MQ REST endpoint.

This typically indicates a network-level problem such as a connection refusal, DNS failure, or TLS handshake error.

Attributes:

Name Type Description
url

The endpoint URL that could not be reached.
Source code in src/pymqrest/exceptions.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
class MQRESTTransportError(MQRESTError):
    """Raised when the transport fails to reach the MQ REST endpoint.

    This typically indicates a network-level problem such as a connection
    refusal, DNS failure, or TLS handshake error.

    Attributes:
        url: The endpoint URL that could not be reached.

    """

    def __init__(self, message: str, *, url: str) -> None:
        """Initialize with the failing endpoint URL.

        Args:
            message: Human-readable error description.
            url: The MQ REST endpoint URL that the transport tried to reach.

        """
        super().__init__(message)
        self.url = url

url = url instance-attribute

__init__(message, *, url)

Initialize with the failing endpoint URL.

Parameters:

Name Type Description Default
message str

Human-readable error description.

 required
url str

The MQ REST endpoint URL that the transport tried to reach.

 required
Source code in src/pymqrest/exceptions.py 
30
31
32
33
34
35
36
37
38
39
def __init__(self, message: str, *, url: str) -> None:
    """Initialize with the failing endpoint URL.

    Args:
        message: Human-readable error description.
        url: The MQ REST endpoint URL that the transport tried to reach.

    """
    super().__init__(message)
    self.url = url

MQRESTResponseError

Thrown when the HTTP request succeeds but the response cannot be parsed — invalid JSON, missing expected fields, unexpected response structure.

Bases: MQRESTError

Raised when the MQ REST response is malformed or unexpected.

This indicates the server returned a response that could not be parsed as valid JSON or did not conform to the expected runCommandJSON response structure.

Attributes:

Name Type Description
response_text

The raw response body, if available.
Source code in src/pymqrest/exceptions.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
class MQRESTResponseError(MQRESTError):
    """Raised when the MQ REST response is malformed or unexpected.

    This indicates the server returned a response that could not be
    parsed as valid JSON or did not conform to the expected
    ``runCommandJSON`` response structure.

    Attributes:
        response_text: The raw response body, if available.

    """

    def __init__(self, message: str, *, response_text: str | None = None) -> None:
        """Initialize with optional response payload text.

        Args:
            message: Human-readable error description.
            response_text: The raw HTTP response body, or ``None`` if
                unavailable.

        """
        super().__init__(message)
        self.response_text = response_text

response_text = response_text instance-attribute

__init__(message, *, response_text=None)

Initialize with optional response payload text.

Parameters:

Name Type Description Default
message str

Human-readable error description.

 required
response_text str | None

The raw HTTP response body, or None if unavailable.

 None
Source code in src/pymqrest/exceptions.py 
54
55
56
57
58
59
60
61
62
63
64
def __init__(self, message: str, *, response_text: str | None = None) -> None:
    """Initialize with optional response payload text.

    Args:
        message: Human-readable error description.
        response_text: The raw HTTP response body, or ``None`` if
            unavailable.

    """
    super().__init__(message)
    self.response_text = response_text

MQRESTAuthError

Thrown when authentication or authorization fails — invalid credentials, expired tokens, insufficient permissions (HTTP 401/403).

from pymqrest.exceptions import MQRESTAuthError

try:
    session.display_qmgr()
except MQRESTAuthError as err:
    print(f"Authentication failed: {err}")

Bases: MQRESTError

Raised when authentication with the MQ REST API fails.

This indicates the server rejected credentials or a required authentication token could not be obtained.

Attributes:

Name Type Description
url

The endpoint URL where authentication failed.
status_code

The HTTP status code, or None if unavailable.
Source code in src/pymqrest/exceptions.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class MQRESTAuthError(MQRESTError):
    """Raised when authentication with the MQ REST API fails.

    This indicates the server rejected credentials or a required
    authentication token could not be obtained.

    Attributes:
        url: The endpoint URL where authentication failed.
        status_code: The HTTP status code, or ``None`` if unavailable.

    """

    def __init__(self, message: str, *, url: str, status_code: int | None = None) -> None:
        """Initialize with the failing endpoint URL and optional status code.

        Args:
            message: Human-readable error description.
            url: The MQ REST endpoint URL where authentication failed.
            status_code: The HTTP status code from the response.

        """
        super().__init__(message)
        self.url = url
        self.status_code = status_code

url = url instance-attribute

status_code = status_code instance-attribute

__init__(message, *, url, status_code=None)

Initialize with the failing endpoint URL and optional status code.

Parameters:

Name Type Description Default
message str

Human-readable error description.

 required
url str

The MQ REST endpoint URL where authentication failed.

 required
status_code int | None

The HTTP status code from the response.

 None
Source code in src/pymqrest/exceptions.py 
79
80
81
82
83
84
85
86
87
88
89
90
def __init__(self, message: str, *, url: str, status_code: int | None = None) -> None:
    """Initialize with the failing endpoint URL and optional status code.

    Args:
        message: Human-readable error description.
        url: The MQ REST endpoint URL where authentication failed.
        status_code: The HTTP status code from the response.

    """
    super().__init__(message)
    self.url = url
    self.status_code = status_code

MQRESTCommandError

Thrown when the MQSC command returns a non-zero completion or reason code. This is the most commonly caught exception — it indicates the command was delivered to MQ but the queue manager rejected it.

from pymqrest.exceptions import MQRESTCommandError

try:
    session.define_qlocal("MY.QUEUE")
except MQRESTCommandError as err:
    print(f"Command failed: {err}")
    print(f"Response payload: {err.payload}")

Note

For DISPLAY commands with no matches, MQ returns reason code 2085 (MQRC_UNKNOWN_OBJECT_NAME). The library treats this as an empty list rather than raising an exception.

Bases: MQRESTError

Raised when the MQ REST response indicates MQSC command failure.

The server returned a valid JSON response, but the completion or reason codes indicate the MQSC command did not succeed.

Attributes:

Name Type Description
payload

The full JSON response payload as a dict.
status_code

The HTTP status code, or None if unavailable.
Source code in src/pymqrest/exceptions.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
class MQRESTCommandError(MQRESTError):
    """Raised when the MQ REST response indicates MQSC command failure.

    The server returned a valid JSON response, but the completion or
    reason codes indicate the MQSC command did not succeed.

    Attributes:
        payload: The full JSON response payload as a dict.
        status_code: The HTTP status code, or ``None`` if unavailable.

    """

    def __init__(
        self,
        message: str,
        *,
        payload: Mapping[str, object],
        status_code: int | None = None,
    ) -> None:
        """Initialize with response payload and HTTP status.

        Args:
            message: Human-readable error description including
                completion and reason codes.
            payload: The full JSON response payload from the MQ REST API.
            status_code: The HTTP status code from the response.

        """
        super().__init__(message)
        self.payload = dict(payload)
        self.status_code = status_code

payload = dict(payload) instance-attribute

status_code = status_code instance-attribute

__init__(message, *, payload, status_code=None)

Initialize with response payload and HTTP status.

Parameters:

Name Type Description Default
message str

Human-readable error description including completion and reason codes.

 required
payload Mapping[str, object]

The full JSON response payload from the MQ REST API.

 required
status_code int | None

The HTTP status code from the response.

 None
Source code in src/pymqrest/exceptions.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def __init__(
    self,
    message: str,
    *,
    payload: Mapping[str, object],
    status_code: int | None = None,
) -> None:
    """Initialize with response payload and HTTP status.

    Args:
        message: Human-readable error description including
            completion and reason codes.
        payload: The full JSON response payload from the MQ REST API.
        status_code: The HTTP status code from the response.

    """
    super().__init__(message)
    self.payload = dict(payload)
    self.status_code = status_code

MQRESTTimeoutError

Thrown when a polling operation exceeds the configured timeout duration.

from pymqrest.exceptions import MQRESTTimeoutError

try:
    session.start_channel_sync("BROKEN.CHL")
except MQRESTTimeoutError as err:
    print(f"Object: {err.name}")
    print(f"Operation: {err.operation}")
    print(f"Elapsed: {err.elapsed:.1f}s")

Bases: MQRESTError

Raised when a synchronous operation exceeds its timeout.

This indicates that a start, stop, or restart operation did not reach the expected state within the configured timeout period.

Attributes:

Name Type Description
name

The MQ object name that timed out.
operation

A description of the operation that timed out (e.g. "start", "stop").
elapsed

The elapsed wall-clock seconds before the timeout.
Source code in src/pymqrest/exceptions.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
class MQRESTTimeoutError(MQRESTError):
    """Raised when a synchronous operation exceeds its timeout.

    This indicates that a start, stop, or restart operation did not
    reach the expected state within the configured timeout period.

    Attributes:
        name: The MQ object name that timed out.
        operation: A description of the operation that timed out
            (e.g. ``"start"``, ``"stop"``).
        elapsed: The elapsed wall-clock seconds before the timeout.

    """

    def __init__(self, message: str, *, name: str, operation: str, elapsed: float) -> None:
        """Initialize with object name, operation, and elapsed time.

        Args:
            message: Human-readable error description.
            name: The MQ object name.
            operation: The operation that timed out.
            elapsed: Seconds elapsed before the timeout was raised.

        """
        super().__init__(message)
        self.name = name
        self.operation = operation
        self.elapsed = elapsed

name = name instance-attribute

operation = operation instance-attribute

elapsed = elapsed instance-attribute

__init__(message, *, name, operation, elapsed)

Initialize with object name, operation, and elapsed time.

Parameters:

Name Type Description Default
message str

Human-readable error description.

 required
name str

The MQ object name.

 required
operation str

The operation that timed out.

 required
elapsed float

Seconds elapsed before the timeout was raised.

 required
Source code in src/pymqrest/exceptions.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
def __init__(self, message: str, *, name: str, operation: str, elapsed: float) -> None:
    """Initialize with object name, operation, and elapsed time.

    Args:
        message: Human-readable error description.
        name: The MQ object name.
        operation: The operation that timed out.
        elapsed: Seconds elapsed before the timeout was raised.

    """
    super().__init__(message)
    self.name = name
    self.operation = operation
    self.elapsed = elapsed

Catching exceptions

Catch the base class for broad error handling, or specific subtypes for targeted recovery:

from pymqrest.exceptions import (
    MQRESTCommandError,
    MQRESTAuthError,
    MQRESTTransportError,
    MQRESTError,
)

try:
    session.define_qlocal("MY.QUEUE", request_parameters={"max_queue_depth": 50000})
except MQRESTCommandError as err:
    # MQSC command failed — check reason code in payload
    print(f"Command failed: {err}")
except MQRESTAuthError:
    # Credentials rejected
    print("Not authorized")
except MQRESTTransportError:
    # Network error
    print("Connection failed")
except MQRESTError as err:
    # Catch-all for any other library exception
    print(f"Unexpected error: {err}")