synology_apm.sdk.exceptions module

APM SDK custom exception hierarchy.

exception synology_apm.sdk.exceptions.APMError(message, error_code=None, response_body=None)

Bases: Exception

Base class for all APM SDK exceptions.

Variables:

  • message – Human-readable error description.

  • error_code – Synology WebAPI or APM REST API error code (if any).

  • response_body – Full JSON response body (for debugging or reporting).

to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.AuthenticationError(message, error_code=None, response_body=None)

Bases: APMError

Login failed or session has expired.

Common causes: - Incorrect username or password - Session expired - Account is locked

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.OTPRequiredError(message, error_code=None, response_body=None)

Bases: APMError

Login requires a two-factor authentication code, and none — or no valid trusted-device registration — was supplied.

Raised by connect() for an account with two-factor authentication enabled when no trusted device is registered for it yet, or the registered device is no longer recognized (e.g. it was revoked). Only synology-apm-cli’s config set command handles this interactively; every other caller should treat it as a hard failure and point the user at that command.

A sibling of AuthenticationError (not a subclass): ERROR_CODES keys must have no subclass relationships with each other (classify_error() does an exact type() lookup), so this is intentionally not class OTPRequiredError(AuthenticationError) even though it is conceptually an authentication failure.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.OTPIncorrectError(message, error_code=None, response_body=None)

Bases: APMError

The supplied two-factor authentication code was incorrect.

Raised by connect() when an otp_code was supplied but rejected. See OTPRequiredError’s docstring for why this is a sibling of AuthenticationError rather than a subclass.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.ResourceNotFoundError(message, resource_type, resource_id, error_code=None, response_body=None)

Bases: _ResourceError

The requested resource does not exist.

Variables:

  • resource_type – Resource type name, e.g. “Workload”, “ProtectionPlan”.

  • resource_id – The ID or name used in the lookup.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.PermissionDeniedError(message, error_code=None, response_body=None)

Bases: APMError

The user lacks sufficient permission for this operation.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.NotSupportedError(message, error_code=None, response_body=None)

Bases: APMError

Feature not supported by this APM version.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.InvalidOperationError(message, resource_type, resource_id, error_code=None, response_body=None)

Bases: _ResourceError

The operation is not valid for the resource’s current state.

Variables:

  • resource_type – Resource type name, e.g. “Workload”.

  • resource_id – The ID of the resource.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.ConnectionTimeoutError(message, error_code=None, response_body=None)

Bases: APMError

Raised when APM did not respond within the configured timeout.

Distinct from a connection failure (unreachable host / refused connection): the request was dispatched but no complete response arrived before the timeout expired.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.BackupServerDisconnectedError(message, error_code=None, response_body=None)

Bases: APMError

The operation failed because the designated backup server is disconnected.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.NotManagementServerError(message, error_code=None, response_body=None)

Bases: APMError

The host is not running APM or is not the primary management server.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.ResourceNotReadyError(message, error_code=None, response_body=None)

Bases: APMError

The resource exists but is not yet in a state where the operation can be performed.

Raised when an operation requires the resource to be ready, such as calling get_download_url_by_ready_result() on a result whose ready_to_download is False.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.PlanNameConflictError(message, resource_type, resource_id, error_code=None, response_body=None)

Bases: _ResourceError

A plan with this name already exists.

Raised by create() and update() when the plan name is already taken.

Variables:

  • resource_type – Plan type — “ProtectionPlan”, “RetirementPlan”, or “TieringPlan”.

  • resource_id – The conflicting plan name.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.PlanInUseError(message, resource_type, resource_id, *, has_workloads=False, has_server_template=False, has_backup_servers=False, error_code=None, response_body=None)

Bases: _ResourceError

Cannot delete the plan because it is still assigned to workloads or backup servers.

Variables:

  • resource_type – Plan type — “ProtectionPlan”, “RetirementPlan”, or “TieringPlan”.

  • resource_id – The plan UUID.

  • has_workloads – Workloads are assigned to this plan.

  • has_server_template – The plan is the default template for a backup server (protection plans only).

  • has_backup_servers – Backup servers are assigned to this tiering plan (tiering plans only).

to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.DuplicateWorkloadError(message, resource_type, resource_id, error_code=None, response_body=None)

Bases: _ResourceError

A workload with the same identity already exists.

Raised by add_file_server() and update_file_server() when a file server at the given IP address is already registered with the same plan on the same backup server.

Variables:

  • resource_type – Always “file_server”.

  • resource_id – The conflicting file server IP address.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.RemoteStorageConflictError(message, resource_type, resource_id, error_code=None, response_body=None)

Bases: _ResourceError

A remote storage with this vault is already registered.

Raised by add() when the vault is already registered with this APM instance.

Variables:

  • resource_type – Always “RemoteStorage”.

  • resource_id – The vault name that caused the conflict.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.RemoteStorageInUseError(message, resource_type, resource_id, error_code=None, response_body=None)

Bases: _ResourceError

Cannot delete the storage because it is referenced by active plans.

Raised by delete() when the storage is still assigned to protection or tiering plans.

Variables:

  • resource_type – Always “RemoteStorage”.

  • resource_id – The storage UUID.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.RemoteStorageEncryptionMismatchError(message, resource_type, resource_id, error_code=None, response_body=None)

Bases: _ResourceError

The vault was originally registered with encryption; relink_encryption_key is required.

Raised by add() when the vault’s encryption mode does not match the current request — the vault was previously set up with client-side encryption, but the request does not include the encryption key from the original registration.

Variables:

  • resource_type – Always “RemoteStorage”.

  • resource_id – The vault name.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.RemoteStorageAuthenticationError(message, resource_type, resource_id, error_code=None, response_body=None)

Bases: _ResourceError

The remote storage provider rejected the given credentials.

Raised by add() and update() when the storage provider (S3, APV, Azure, etc.) rejects the given credentials — e.g. an invalid access key/secret key, or (for Azure) an invalid Microsoft Entra application tenant ID, client ID, or secret. The message is generally the provider’s own diagnostic text (describing, e.g., an invalid key or an unrecognized tenant/application); a generic description is used on the rare path where the provider supplies none.

Variables:

  • resource_type – Always “RemoteStorage”.

  • resource_id – For add(), usually the vault/container name; falls back to the endpoint (or “” for endpoint-free types) when the failure happens before a vault name is known. For update(), the storage UUID.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.RemoteStorageUnmanagedCatalogError(message, *, vault_name, catalog_count)

Bases: APMError

The vault contains pre-existing backup catalogs not linked to any plan.

Raised by add() when pre-existing catalogs are detected and no retirement plan was provided in the request. Provide unmanaged_retirement_plan in the add request to relink those catalogs to a retirement plan.

Variables:

  • vault_name – Vault or bucket name where unmanaged catalogs were found.

  • catalog_count – Number of unmanaged catalog entries detected.

to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.APIError(message, error_code=None, response_body=None)

Bases: APMError

APM REST API returned an error not covered by a more specific exception class.

Report the error_code to the SDK maintainers for finer-grained handling.

add_note()

Exception.add_note(note) – add a note to the exception

args
to_dict()

Return a JSON-safe dict of this exception’s semantic fields.

Subclasses that add fields (e.g. _ResourceError, PlanInUseError, RemoteStorageUnmanagedCatalogError) override this and extend super().to_dict(); a subclass adding no fields needs no override.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception synology_apm.sdk.exceptions.KeyringUnavailableError

Bases: RuntimeError

Raised when the OS keyring backend is unavailable or an operation fails.

Extends RuntimeError directly (not APMError): it signals a local OS-keyring failure, not a REST API error, and carries no error_code / response_body.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

synology_apm.sdk.exceptions.classify_error(exc)

Return the ERROR_CODES classification for exc, or None if unclassified.

Every classified type in ERROR_CODES is exact (no further subclassing), so this is a direct type lookup, not an isinstance walk.