Skip to content

Exceptions

exceptions

Classes:

Functions:

ActualError

Bases: Exception

General error with Actual. The error message should provide more information.

ActualInvalidOperationError

Bases: ActualError

Invalid operation requested.

Usually happens when a request has been done, but it's missing one of the required parameters.

AuthorizationError

Bases: ActualError

When the login fails due to invalid credentials, or a request has been done with the wrong credentials.

Potential causes are invalid password or token.

UnknownFileId

Bases: ActualError

When the file_id that has been set does not exist on the server.

InvalidZipFile

Bases: ActualError

The validation fails when loading a zip file, either because it's an invalid zip file or the file is corrupted.

InvalidFile

Bases: ActualError

The changes being synced are part of an old group, which means the file has been reset.

The file needs to be re-downloaded. This error should not happen in normal circumstances.

ActualDecryptionError

Bases: ActualError

The decryption for the file failed.

This can happen for a multitude or reasons, like the password is wrong, the file is corrupted, or when the password is not provided but the file is encrypted.

ActualOverflowError

Bases: ActualError

The HULC timestamp counter exceeded the maximum value of 0xFFFF (65535).

This means too many messages were generated within the same millisecond.

ActualSplitTransactionError

Bases: ActualError

The split transaction is invalid.

Most likely because the sum of splits is not equal to the full amount of the transaction.

ActualBankSyncError 

ActualBankSyncError(
    error_type: str,
    status: str | None = None,
    reason: str | None = None,
)

Bases: ActualError

The bank sync had an error.

Could happen due to the service being unavailable or due to authentication issues with the third-party service. This likely indicates a problem with the configuration of the bank sync, not an issue with this library.

Source code in actual/exceptions.py 
112
113
def __init__(self, error_type: str, status: str | None = None, reason: str | None = None):
    self.error_type, self.status, self.reason = error_type, status, reason

get_exception_from_response 

get_exception_from_response(
    response: Response,
) -> Exception
Source code in actual/exceptions.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
def get_exception_from_response(response: httpx.Response) -> Exception:
    text = response.content.decode()
    if text == "internal-error" or response.status_code == 500:
        return ActualError(text)
    # taken from
    # https://github.com/actualbudget/actual-server/blob/6e9eddeb561b0d9f2bbb6301c3e2c30b4effc522/src/app-sync.js#L107
    elif text == "file-has-new-key":
        return ActualError(f"{text}: The data is encrypted with a different key")
    elif text == "file-has-reset":
        return InvalidFile(
            f"{text}: The changes being synced are part of an old group, which means the file has been reset. "
            f"User needs to re-download."
        )
    elif text in ("file-not-found", "file-needs-upload"):
        raise UnknownFileId(text)
    elif text == "file-old-version":
        raise InvalidFile(f"{text}: SYNC_FORMAT_VERSION was generated with an old format")
    # use a fallback using the error text for mypy
    return ActualError(text)