Skip to content

Exceptions

All library exceptions derive from MregApiBaseError.

HTTP response status errors (ResponseError and subclasses) compose the original HTTP response and expose parsed error details for errors that derive from the server's drf-standardized-errors errors.

exceptions

Exception classes for MREG API errors.

APIError

Bases: ResponseError

Deprecated alias for ResponseError.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

BadRequestError

Bases: ClientError

HTTP 400 Bad Request.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

CacheError

Bases: MregApiBaseError

Error related to caching.

CacheMiss

Bases: CacheError

Cache miss error.

ClientError

Bases: HTTPStatusError

HTTP 4xx client error.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

ConflictError

Bases: ClientError

HTTP 409 Conflict.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

ConnectionFailedError

Bases: TransportError

Could not establish or complete the connection to the server.

EntityAlreadyExists

Bases: EntityConflictError

Entity already exists when none was expected.

__init__

__init__(
    message: str = "",
    *,
    model: type | str | None = None,
    identifier: object = None,
)

Initialize an EntityError.

Parameters:

Name Type Description Default
message str

A human-readable error message.

''
model type | str | None

The model type (or its name) the operation concerned.

None
identifier object

The identifier (name/id/ref) that was looked up.

None

EntityConflictError

Bases: EntityError

A mutating operation's precondition on entity state was not met.

Either the entity already existed when it was expected to be absent, or a required relation between entities was absent.

__init__

__init__(
    message: str = "",
    *,
    model: type | str | None = None,
    identifier: object = None,
)

Initialize an EntityError.

Parameters:

Name Type Description Default
message str

A human-readable error message.

''
model type | str | None

The model type (or its name) the operation concerned.

None
identifier object

The identifier (name/id/ref) that was looked up.

None

EntityError

Bases: MregApiBaseError

A request succeeded but the result or state was not as required.

Never stems from an HTTP response failure; always indicates a problem with the entity state after successfully completing the request.

__init__

__init__(
    message: str = "",
    *,
    model: type | str | None = None,
    identifier: object = None,
)

Initialize an EntityError.

Parameters:

Name Type Description Default
message str

A human-readable error message.

''
model type | str | None

The model type (or its name) the operation concerned.

None
identifier object

The identifier (name/id/ref) that was looked up.

None

EntityLookupError

Bases: EntityError

A resolve/read operation did not yield exactly one entity.

__init__

__init__(
    message: str = "",
    *,
    model: type | str | None = None,
    identifier: object = None,
)

Initialize an EntityError.

Parameters:

Name Type Description Default
message str

A human-readable error message.

''
model type | str | None

The model type (or its name) the operation concerned.

None
identifier object

The identifier (name/id/ref) that was looked up.

None

EntityNotFound

Bases: EntityLookupError

No entity found when at least one was expected.

__init__

__init__(
    message: str = "",
    *,
    model: type | str | None = None,
    identifier: object = None,
)

Initialize an EntityError.

Parameters:

Name Type Description Default
message str

A human-readable error message.

''
model type | str | None

The model type (or its name) the operation concerned.

None
identifier object

The identifier (name/id/ref) that was looked up.

None

EntityOwnershipMismatch

Bases: EntityRelationMissing

Deprecated alias for EntityRelationMissing.

__init__

__init__(
    message: str = "",
    *,
    model: type | str | None = None,
    identifier: object = None,
)

Initialize an EntityError.

Parameters:

Name Type Description Default
message str

A human-readable error message.

''
model type | str | None

The model type (or its name) the operation concerned.

None
identifier object

The identifier (name/id/ref) that was looked up.

None

EntityRelationMissing

Bases: EntityConflictError

A required relation between two entities is absent (e.g. role lacks a label).

__init__

__init__(
    message: str = "",
    *,
    model: type | str | None = None,
    identifier: object = None,
)

Initialize an EntityError.

Parameters:

Name Type Description Default
message str

A human-readable error message.

''
model type | str | None

The model type (or its name) the operation concerned.

None
identifier object

The identifier (name/id/ref) that was looked up.

None

ForbiddenError

Bases: ClientError

HTTP 403 Forbidden.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

ForceMissing

Bases: PreconditionError

A precondition failed that force=True would override.

HTTPStatusError

Bases: ResponseError

Server returned a 4xx or 5xx status code.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

IPNetworkError

Bases: ValueError, MregApiBaseError

Error class for IP network/address errors.

InputFailure

Bases: MregApiBaseError, ValueError

Error class for input failure.

InternalError

Bases: MregApiBaseError

Error class for internal errors.

InvalidAuthTokenError

Bases: UnauthorizedError

Invalid authentication token.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

InvalidIPAddress

Bases: IPNetworkError

Entity is not a valid IP address.

InvalidIPv4Address

Bases: InvalidIPAddress

Entity is not a valid IPv4 address.

InvalidIPv4Network

Bases: InvalidNetwork

Entity is not a valid IPv4 network.

InvalidIPv6Address

Bases: InvalidIPAddress

Entity is not a valid IPv6 address.

InvalidIPv6Network

Bases: InvalidNetwork

Entity is not a valid IPv6 network.

InvalidNetwork

Bases: IPNetworkError

Entity is not a valid network.

LoginFailedError

Bases: UnauthorizedError

Login failed.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

MREGError pydantic-model

Bases: BaseModel

Details of an MREG error.

Show JSON schema:
{
  "description": "Details of an MREG error.",
  "properties": {
    "code": {
      "title": "Code",
      "type": "string"
    },
    "detail": {
      "title": "Detail",
      "type": "string"
    },
    "attr": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Attr"
    }
  },
  "required": [
    "code",
    "detail",
    "attr"
  ],
  "title": "MREGError",
  "type": "object"
}

Fields:

attr pydantic-field

attr: str | None

The attribute (field) associated with the error, if any.

code pydantic-field

code: str

The error code identifying the type of error.

detail pydantic-field

detail: str

Human-readable representation of the error.

fmt_error

fmt_error() -> str

Format the error message.

Returns:

Type Description
str

A formatted error message.

MREGErrorResponse pydantic-model

Bases: BaseModel

MREG error response.

Show JSON schema:
{
  "$defs": {
    "MREGError": {
      "description": "Details of an MREG error.",
      "properties": {
        "code": {
          "title": "Code",
          "type": "string"
        },
        "detail": {
          "title": "Detail",
          "type": "string"
        },
        "attr": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Attr"
        }
      },
      "required": [
        "code",
        "detail",
        "attr"
      ],
      "title": "MREGError",
      "type": "object"
    }
  },
  "description": "MREG error response.",
  "properties": {
    "type": {
      "title": "Type",
      "type": "string"
    },
    "errors": {
      "default": [],
      "items": {
        "$ref": "#/$defs/MREGError"
      },
      "title": "Errors",
      "type": "array"
    }
  },
  "required": [
    "type"
  ],
  "title": "MREGErrorResponse",
  "type": "object"
}

Fields:

detail cached property

detail: str

Get the detail field of the error(s).

Most MREG error responses only contain a single error object.

__bool__

__bool__() -> bool

Response contains MREGError objects if True, else False.

as_json_str

as_json_str(indent: int = 2) -> str

Convert the error response to a JSON string.

Parameters:

Name Type Description Default
indent int

The indentation level for the JSON string.

2

Returns:

Type Description
str

A JSON string representation of the error response.

as_str

as_str() -> str

Convert the error response to a string.

Returns:

Type Description
str

A string representation of the error response.

MregApiBaseError

Bases: Exception

Base exception class for MREG API exceptions.

MregValidationError

Bases: MregApiBaseError

Validation error class for MREG API.

Stems from Pydantic ValidationError but adds context about the API request that caused the validation to fail.

from_pydantic classmethod

from_pydantic(
    e: ValidationError, context: str | None = None
) -> MregValidationError

Create an MregValidationError from a Pydantic MregValidationError.

Parameters:

Name Type Description Default
e ValidationError

The Pydantic MregValidationError.

required
context str | None

What was being validated (e.g., "JSON", "string", "object").

None

Returns:

Type Description
MregValidationError

The created MregValidationError.

MultipleEntitiesFound

Bases: EntityLookupError

Multiple entities found when only one was expected.

__init__

__init__(
    message: str = "",
    *,
    model: type | str | None = None,
    identifier: object = None,
)

Initialize an EntityError.

Parameters:

Name Type Description Default
message str

A human-readable error message.

''
model type | str | None

The model type (or its name) the operation concerned.

None
identifier object

The identifier (name/id/ref) that was looked up.

None

NotFoundError

Bases: ClientError

HTTP 404 Not Found.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

PreconditionError

Bases: MregApiBaseError

Client-side guard: an operation's precondition was not met.

Raised before or independently of an HTTP request when the library refuses to perform an operation (e.g. deleting a resource that is still in use).

ResponseError

Bases: MregApiBaseError

Base class for errors that always carry an HTTP response.

Parses error details from the MREG API response if present.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

ServerError

Bases: HTTPStatusError

HTTP 5xx server error.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

TooManyResults

Bases: MregApiBaseError

API returned too many results.

TransportError

Bases: MregApiBaseError

Request was sent but no usable response was received (e.g. connection failure).

UnauthorizedError

Bases: ClientError

HTTP 401 Unauthorized.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

UnexpectedDataError

Bases: UnexpectedResponseError

Deprecated alias for UnexpectedResponseError.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

UnexpectedResponseError

Bases: ResponseError

Server returned a success status but a body/content we could not use.

detail cached property

detail: str

Clean human-readable error message from the response.

Joins the detail of each parsed error with "; ". Empty if the response has no parseable errors.

details property

details: str

Get the error details from the response.

details_json property

details_json: str

Get the error details from the response.

error_message cached property

error_message: str

Verbose error text (with codes), falling back to raw response text.

error_message_json cached property

error_message_json: str

Verbose error text (with codes), falling back to raw response text.

errors cached property

Get the parsed MREG errors from the response.

Returns:

Type Description
MREGErrorResponse

The MREGErrorResponse object, or a default MREGErrorResponse with type

MREGErrorResponse

"unknown" if the response could not be parsed.

request property

request: Request

The request that triggered the exception.

response property

response: Response

The response object associated with the error.

status_code property

status_code: int

The HTTP status code of the response.

__init__

__init__(message: str = '', *, response: Response)

Initialize a ResponseError.

Parameters:

Name Type Description Default
message str

An optional message override. When empty, the message is derived from the response via formatted_message.

''
response Response

The response object that triggered the exception.

required

__str__

__str__() -> str

Return the full formatted error message (request info + details).

formatted_message

formatted_message(*, json: bool = False) -> str

Get a formatted, human-readable error message.

The message has a status-first header line ({code} {reason}: {method} {url}) followed by the error detail(s): a pluralized N error(s): list of the parsed errors, or the endpoint-not-found hint / explicit message / raw response text otherwise.

Parameters:

Name Type Description Default
json bool

Render the parsed errors as a JSON block instead of the list.

False

Returns:

Type Description
str

The formatted error message.

Example
400 Bad Request: POST http://localhost/api/v1/hosts/
2 errors:
  name: This field is required.  (required)
  contact: Enter a valid email.  (invalid)

fmt_error_code

fmt_error_code(code: str) -> str

Format the error code.

Parameters:

Name Type Description Default
code str

The error code to format.

required

Returns:

Type Description
str

The formatted error code.

http_error_class

http_error_class(status_code: int) -> type[HTTPStatusError]

Get the appropriate exception class for a given HTTP status code.

Parameters:

Name Type Description Default
status_code int

The HTTP status code.

required

Returns:

Type Description
type[HTTPStatusError]

type[HTTPStatusError]: The exception class corresponding to the status code.

parse_mreg_error

parse_mreg_error(
    resp: Response,
) -> MREGErrorResponse | None

Parse an MREG error response.

Parameters:

Name Type Description Default
resp Response

The response object to parse.

required

Returns:

Type Description
MREGErrorResponse | None

A MREGErrorResponse object or None if it cannot be parsed.