Errors

The Files.com Python SDK will return errors by raising exceptions. There are many exception classes defined in the Files SDK that correspond to specific errors.

The raised exceptions come from two categories:

SDK Exceptions - errors that originate within the SDK
API Exceptions - errors that occur due to the response from the Files.com API. These errors are grouped into common error types.

There are several types of exceptions within each category. Exception classes indicate different types of errors and are named in a fashion that describe the general premise of the originating error. More details can be found in the err object message.

Use standard Python exception handling to detect and deal with errors. It is generally recommended to handle specific errors first, then handle the general files_sdk.error.Error exception as a catch-all.

Example Error Handling

import files_sdk

try:
  session = files_sdk.session.create({ "username": "USERNAME", "password": "BADPASSWORD" })
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

Error Types

SDK Errors

SDK errors are general errors that occur within the SDK code. Each exception class inherits from a standard Error base class.

Example SDK Exception Class Inheritance Structure

files_sdk.error.APIConnectionError -> files_sdk.error.Error -> Exception

SDK Exception Classes

Error Class Name	Description
`APIConnectionError`	The Files.com API cannot be reached, or its response is malformed or unreliable
`DeadlineExceededError`	An `APIConnectionError`: the operation ran out of the time its `request_timeout` or `deadline` allowed
`OperationCancelledError`	The operation's `cancel_token` was cancelled
`ClientClosedError`	An `OperationCancelledError`: the operation's client was closed
`AuthenticationError`	Not enough authentication information has been provided
`InvalidRequestError`	The SDK refused to go on, such as for a file that changed while it transferred, a checkpoint it cannot use, or a remote file whose upload already failed
`InvalidParameterError`	An `InvalidRequestError`: a passed in parameter or option is invalid
`MissingParameterError`	An `InvalidRequestError`: a method parameter is missing
`TransferPausedError`	A transfer stopped because its `pause_token` was paused; its `checkpoint` resumes it
`FileMigrationError`	A copy or move that was waited for failed or was cancelled; its `migration`, when Files.com made one, says why
`NotImplementedError`	The called method has not be implemented by the SDK

APIConnectionError, DeadlineExceededError and OperationCancelledError have phase, the step that failed, and remote_outcome_unknown, which is True when the request may already have reached Files.com.

Local file problems raise Python's own OSError subclasses, such as files_sdk.localfs.AccessNotKept when a download cannot keep a replaced file's owner, group or access control list. A remote file opened with files_sdk.open() raises io.UnsupportedOperation for what it cannot do, such as seek(), as Python's own files do.

API Errors

API errors are errors returned by the Files.com API. Each exception class inherits from an error group base class. The error group base class indicates a particular type of error.

Example API Exception Class Inheritance Structure

files_sdk.error.FolderAdminPermissionRequiredError -> files_sdk.error.NotAuthorizedError -> files_sdk.error.APIError -> files_sdk.error.Error -> Exception

API Exception Classes

Error Class Name	Error Group
`AgentUpgradeRequiredError`	`BadRequestError`
`AttachmentTooLargeError`	`BadRequestError`
`CannotDownloadDirectoryError`	`BadRequestError`
`CantMoveWithMultipleLocationsError`	`BadRequestError`
`DatetimeParseError`	`BadRequestError`
`DestinationSameError`	`BadRequestError`
`DestinationSiteMismatchError`	`BadRequestError`
`DoesNotSupportSortingError`	`BadRequestError`
`FolderMustNotBeAFileError`	`BadRequestError`
`FoldersNotAllowedError`	`BadRequestError`
`InternalGeneralErrorError`	`BadRequestError`
`InvalidBodyError`	`BadRequestError`
`InvalidCursorError`	`BadRequestError`
`InvalidCursorTypeForSortError`	`BadRequestError`
`InvalidEtagsError`	`BadRequestError`
`InvalidFilterAliasCombinationError`	`BadRequestError`
`InvalidFilterFieldError`	`BadRequestError`
`InvalidFilterParamError`	`BadRequestError`
`InvalidFilterParamFormatError`	`BadRequestError`
`InvalidFilterParamValueError`	`BadRequestError`
`InvalidInputEncodingError`	`BadRequestError`
`InvalidInterfaceError`	`BadRequestError`
`InvalidOauthProviderError`	`BadRequestError`
`InvalidPathError`	`BadRequestError`
`InvalidReturnToUrlError`	`BadRequestError`
`InvalidSearchQueryError`	`BadRequestError`
`InvalidSortFieldError`	`BadRequestError`
`InvalidSortFilterCombinationError`	`BadRequestError`
`InvalidUploadOffsetError`	`BadRequestError`
`InvalidUploadPartGapError`	`BadRequestError`
`InvalidUploadPartSizeError`	`BadRequestError`
`InvalidWorkspaceIdHeaderError`	`BadRequestError`
`MethodNotAllowedError`	`BadRequestError`
`MultipleSortParamsNotAllowedError`	`BadRequestError`
`NoValidInputParamsError`	`BadRequestError`
`OffsetUploadNotAllowedWithMalwareScanningError`	`BadRequestError`
`PartNumberTooLargeError`	`BadRequestError`
`PathCannotHaveTrailingWhitespaceError`	`BadRequestError`
`ReauthenticationNeededFieldsError`	`BadRequestError`
`RequestBodyTooLargeError`	`BadRequestError`
`RequestParamsContainInvalidCharacterError`	`BadRequestError`
`RequestParamsInvalidError`	`BadRequestError`
`RequestParamsRequiredError`	`BadRequestError`
`SearchAllOnChildPathError`	`BadRequestError`
`UnrecognizedSortIndexError`	`BadRequestError`
`UnsupportedCurrencyError`	`BadRequestError`
`UnsupportedHttpResponseFormatError`	`BadRequestError`
`UnsupportedMediaTypeError`	`BadRequestError`
`UserIdInvalidError`	`BadRequestError`
`UserIdOnUserEndpointError`	`BadRequestError`
`UserRequiredError`	`BadRequestError`
`AdditionalAuthenticationRequiredError`	`NotAuthenticatedError`
`ApiKeySessionsNotSupportedError`	`NotAuthenticatedError`
`AuthenticationRequiredError`	`NotAuthenticatedError`
`BundleRegistrationCodeFailedError`	`NotAuthenticatedError`
`InboxRegistrationCodeFailedError`	`NotAuthenticatedError`
`InvalidCredentialsError`	`NotAuthenticatedError`
`InvalidOauthError`	`NotAuthenticatedError`
`InvalidOrExpiredCodeError`	`NotAuthenticatedError`
`InvalidSessionError`	`NotAuthenticatedError`
`InvalidUsernameOrPasswordError`	`NotAuthenticatedError`
`LockedOutError`	`NotAuthenticatedError`
`LockoutRegionMismatchError`	`NotAuthenticatedError`
`OneTimePasswordIncorrectError`	`NotAuthenticatedError`
`TwoFactorAuthenticationErrorError`	`NotAuthenticatedError`
`TwoFactorAuthenticationSetupExpiredError`	`NotAuthenticatedError`
`ApiKeyIsDisabledError`	`NotAuthorizedError`
`ApiKeyIsPathRestrictedError`	`NotAuthorizedError`
`ApiKeyOnlyForDesktopAppError`	`NotAuthorizedError`
`ApiKeyOnlyForFileOperationsError`	`NotAuthorizedError`
`ApiKeyOnlyForMobileAppError`	`NotAuthorizedError`
`ApiKeyOnlyForOfficeIntegrationError`	`NotAuthorizedError`
`BillingInformationHiddenError`	`NotAuthorizedError`
`BillingPermissionRequiredError`	`NotAuthorizedError`
`BundleMaximumUsesReachedError`	`NotAuthorizedError`
`BundlePermissionRequiredError`	`NotAuthorizedError`
`CannotAdministerHigherLevelUserError`	`NotAuthorizedError`
`CannotLoginWhileUsingKeyError`	`NotAuthorizedError`
`CantActForOtherUserError`	`NotAuthorizedError`
`ContactAdminForPasswordChangeHelpError`	`NotAuthorizedError`
`FilesAgentFailedAuthorizationError`	`NotAuthorizedError`
`FolderAdminOrBillingPermissionRequiredError`	`NotAuthorizedError`
`FolderAdminPermissionRequiredError`	`NotAuthorizedError`
`FullPermissionRequiredError`	`NotAuthorizedError`
`HistoryPermissionRequiredError`	`NotAuthorizedError`
`InAppAiAssistantUnavailableError`	`NotAuthorizedError`
`InsufficientPermissionForParamsError`	`NotAuthorizedError`
`InsufficientPermissionForSiteError`	`NotAuthorizedError`
`MoverAccessDeniedError`	`NotAuthorizedError`
`MoverPackageRequiredError`	`NotAuthorizedError`
`MustAuthenticateWithApiKeyError`	`NotAuthorizedError`
`NeedAdminPermissionForInboxError`	`NotAuthorizedError`
`NonAdminsMustQueryByFolderOrPathError`	`NotAuthorizedError`
`NotAllowedToCreateBundleError`	`NotAuthorizedError`
`NotEnqueuableSyncError`	`NotAuthorizedError`
`PasswordChangeNotRequiredError`	`NotAuthorizedError`
`PasswordChangeRequiredError`	`NotAuthorizedError`
`PaymentMethodErrorError`	`NotAuthorizedError`
`PreviewOnlyPermissionCannotDownloadError`	`NotAuthorizedError`
`ReadOnlySessionError`	`NotAuthorizedError`
`ReadPermissionRequiredError`	`NotAuthorizedError`
`ReauthenticationFailedError`	`NotAuthorizedError`
`ReauthenticationFailedFinalError`	`NotAuthorizedError`
`ReauthenticationNeededActionError`	`NotAuthorizedError`
`RecaptchaFailedError`	`NotAuthorizedError`
`RemoteDesktopDebugLoggingDisabledError`	`NotAuthorizedError`
`RootFolderBehaviorSiteAdminRequiredError`	`NotAuthorizedError`
`RootFolderBehaviorSkipSiteAdminRequiredError`	`NotAuthorizedError`
`SelfManagedRequiredError`	`NotAuthorizedError`
`SiteAdminOrPartnerAdminPermissionRequiredError`	`NotAuthorizedError`
`SiteAdminOrWorkspaceAdminOrFolderAdminPermissionRequiredError`	`NotAuthorizedError`
`SiteAdminOrWorkspaceAdminOrPartnerAdminOrFolderAdminPermissionRequiredError`	`NotAuthorizedError`
`SiteAdminOrWorkspaceAdminOrPartnerAdminPermissionRequiredError`	`NotAuthorizedError`
`SiteAdminOrWorkspaceAdminPermissionRequiredError`	`NotAuthorizedError`
`SiteAdminRequiredError`	`NotAuthorizedError`
`SiteFilesAreImmutableError`	`NotAuthorizedError`
`TwoFactorAuthenticationRequiredError`	`NotAuthorizedError`
`UserIdWithoutSiteAdminError`	`NotAuthorizedError`
`WriteAndBundlePermissionRequiredError`	`NotAuthorizedError`
`WritePermissionRequiredError`	`NotAuthorizedError`
`ApiKeyNotFoundError`	`NotFoundError`
`BundlePathNotFoundError`	`NotFoundError`
`BundleRegistrationNotFoundError`	`NotFoundError`
`CodeNotFoundError`	`NotFoundError`
`FileNotFoundError`	`NotFoundError`
`FileUploadNotFoundError`	`NotFoundError`
`GroupNotFoundError`	`NotFoundError`
`InboxNotFoundError`	`NotFoundError`
`NestedNotFoundError`	`NotFoundError`
`PlanNotFoundError`	`NotFoundError`
`SiteNotFoundError`	`NotFoundError`
`UserNotFoundError`	`NotFoundError`
`AgentPushUpdateBlockedError`	`ProcessingFailureError`
`AgentUnavailableError`	`ProcessingFailureError`
`AiTaskCannotBeRunManuallyError`	`ProcessingFailureError`
`AlreadyCompletedError`	`ProcessingFailureError`
`AutomationCannotBeRunManuallyError`	`ProcessingFailureError`
`BehaviorNotAllowedOnRemoteServerError`	`ProcessingFailureError`
`BufferedUploadDisabledForThisDestinationError`	`ProcessingFailureError`
`BundleOnlyAllowsPreviewsError`	`ProcessingFailureError`
`BundleOperationRequiresSubfolderError`	`ProcessingFailureError`
`ConfigurationLockedPathError`	`ProcessingFailureError`
`CouldNotCreateParentError`	`ProcessingFailureError`
`DestinationExistsError`	`ProcessingFailureError`
`DestinationFolderLimitedError`	`ProcessingFailureError`
`DestinationParentConflictError`	`ProcessingFailureError`
`DestinationParentDoesNotExistError`	`ProcessingFailureError`
`ExceededRuntimeLimitError`	`ProcessingFailureError`
`ExpectationAlreadyHasOpenWindowError`	`ProcessingFailureError`
`ExpectationNotManualTriggerError`	`ProcessingFailureError`
`ExpiredPrivateKeyError`	`ProcessingFailureError`
`ExpiredPublicKeyError`	`ProcessingFailureError`
`ExportFailureError`	`ProcessingFailureError`
`ExportNotReadyError`	`ProcessingFailureError`
`FailedToChangePasswordError`	`ProcessingFailureError`
`FileLockedError`	`ProcessingFailureError`
`FileNotUploadedError`	`ProcessingFailureError`
`FilePendingProcessingError`	`ProcessingFailureError`
`FileProcessingErrorError`	`ProcessingFailureError`
`FileTooBigToDecryptError`	`ProcessingFailureError`
`FileTooBigToEncryptError`	`ProcessingFailureError`
`FileUploadedToWrongRegionError`	`ProcessingFailureError`
`FilenameTooLongError`	`ProcessingFailureError`
`FolderLockedError`	`ProcessingFailureError`
`FolderNotEmptyError`	`ProcessingFailureError`
`HistoryUnavailableError`	`ProcessingFailureError`
`InvalidBundleCodeError`	`ProcessingFailureError`
`InvalidFileTypeError`	`ProcessingFailureError`
`InvalidFilenameError`	`ProcessingFailureError`
`InvalidPriorityColorError`	`ProcessingFailureError`
`InvalidRangeError`	`ProcessingFailureError`
`InvalidSiteError`	`ProcessingFailureError`
`InvalidZipFileError`	`ProcessingFailureError`
`MetadataNotSupportedOnRemotesError`	`ProcessingFailureError`
`ModelSaveErrorError`	`ProcessingFailureError`
`MultipleProcessingErrorsError`	`ProcessingFailureError`
`PathTooLongError`	`ProcessingFailureError`
`RecipientAlreadySharedError`	`ProcessingFailureError`
`RemoteEntryReadOnlyError`	`ProcessingFailureError`
`RemoteServerErrorError`	`ProcessingFailureError`
`ResourceBelongsToParentSiteError`	`ProcessingFailureError`
`ResourceLockedError`	`ProcessingFailureError`
`SubfolderLockedError`	`ProcessingFailureError`
`SyncInProgressError`	`ProcessingFailureError`
`TwoFactorAuthenticationCodeAlreadySentError`	`ProcessingFailureError`
`TwoFactorAuthenticationCountryBlacklistedError`	`ProcessingFailureError`
`TwoFactorAuthenticationGeneralErrorError`	`ProcessingFailureError`
`TwoFactorAuthenticationMethodUnsupportedErrorError`	`ProcessingFailureError`
`TwoFactorAuthenticationUnsubscribedRecipientError`	`ProcessingFailureError`
`UpdatesNotAllowedForRemotesError`	`ProcessingFailureError`
`DuplicateShareRecipientError`	`RateLimitedError`
`ReauthenticationRateLimitedError`	`RateLimitedError`
`TooManyConcurrentLoginsError`	`RateLimitedError`
`TooManyConcurrentRequestsError`	`RateLimitedError`
`TooManyLoginAttemptsError`	`RateLimitedError`
`TooManyRequestsError`	`RateLimitedError`
`TooManySharesError`	`RateLimitedError`
`AutomationsUnavailableError`	`ServiceUnavailableError`
`LockOperationBusyError`	`ServiceUnavailableError`
`MigrationInProgressError`	`ServiceUnavailableError`
`SearchUnavailableError`	`ServiceUnavailableError`
`SiteDisabledError`	`ServiceUnavailableError`
`UploadsUnavailableError`	`ServiceUnavailableError`
`AccountAlreadyExistsError`	`SiteConfigurationError`
`AccountOverdueError`	`SiteConfigurationError`
`NoAccountForSiteError`	`SiteConfigurationError`
`SiteWasRemovedError`	`SiteConfigurationError`
`TrialExpiredError`	`SiteConfigurationError`
`TrialLockedError`	`SiteConfigurationError`
`UserRequestsEnabledRequiredError`	`SiteConfigurationError`