.. _error_handling:

===============
Error handling
===============

When an error occurs within the SDK, a :ref:`BiosealException<id3_bioseal_bioseal_exception>` exception is thrown. Generally you should wrap all invocations of the API into a try-catch block. 

.. tab-set::

    .. tab-item:: Python
      :sync: Python

      .. code:: Python

        try:
            # ...
        except id3bioseal.BiosealException as ex:
            print(f"SDK exception: {ex}")

    .. tab-item:: Dart
      :sync: Dart

      .. code:: dart

        try
        {
           // ...
        }
        on BiosealException catch (e) {
            print('Bioseal SDK exception: $e');
        }

    .. tab-item:: C#
      :sync: C#

      .. code:: C#

        try
        {
           // ...
        }
        catch (BiosealException ex)
        {
            Console.WriteLine(ex.Message);
        }

    .. tab-item:: Java
      :sync: Java

      .. code:: Java

        try {
            // ...
        }
        catch (BiosealException ex) {
        }

    .. tab-item:: Swift
      :sync: Swift

      .. code:: Swift

        do {
            // ...
        } catch let error as BiosealException {
            print(error.message)
        }

    .. tab-item:: C
      :sync: C

      In C and C++ languages, you have to handle the errors manually. The possible error codes are listed in the :ref:`BiosealError<id3_bioseal_bioseal_error_enum>` enumeration.

      An example is given below:
      
      .. code-block:: cpp

        int err = id3BiosealLicense_CheckLicense(path, nullptr);
        if (err != id3BiosealError_Success) {
          // handle error here.
        }


Error Codes
-----------

BioSeal Error Codes
~~~~~~~~~~~~~~~~~~~

.. list-table:: 
   :header-rows: 1
   :widths: 10 20 50

   * - Code
     - Name
     - Description
   * - 0
     - Success
     - No error
   * - -1
     - InsufficientBuffer
     - The given buffer is too small
   * - -2
     - ObjectDoesNotExist
     - The requested object does not exist; a 'null' should be returned if possible
   * - -8000
     - Base
     - Base error code for BioSeal module
   * - -8001
     - InvalidHandle
     - The handle is invalid
   * - -8002
     - InvalidParameter
     - The parameter is invalid
   * - -8003
     - ExceptionInCallback
     - An exception was fired in the callback
   * - -8004
     - JavaException
     - An exception was fired in JNI
   * - -8005
     - ResourceNotFound
     - Resource not found
   * - -8006
     - MemoryError
     - An internal error has been fired
   * - -8007
     - InternalError
     - A memory error has been fired
   * - -8008
     - DownloadError
     - Error in the internal download process
   * - -8009
     - InvalidInputFormat
     - Invalid input format
   * - -8010
     - BadInputLotl
     - The LOTL is malformed
   * - -8011
     - BadInputTsl
     - The TSL does not conform to ETSI TS 119 612
   * - -8012
     - BadInputManifest
     - The manifest is malformed
   * - -8013
     - UnsupportedAfnorXpZ42_101Id
     - Unsupported Afnor XP Z42-101 identifier
   * - -8014
     - DecodingFailed
     - Decoding failed
   * - -8015
     - BiosealExpired
     - The BioSeal has expired
   * - -8016
     - InvalidCertificationChain
     - Invalid certification chain
   * - -8017
     - InvalidSignature
     - Invalid signature
   * - -8018
     - AuthorizedUsageFailed
     - Authorized usage failed
   * - -8019
     - SigningCertificateExpired
     - The signing certificate was expired when the BioSeal was generated
   * - -8020
     - RevocationInfoValidityPeriod
     - Invalid revocation info validity period
   * - -8021
     - DecryptionError
     - An unexpected error occurred during decryption
   * - -8022
     - LanguageNotAvailable
     - Language not found
   * - -8023
     - BiosealNotDecoded
     - The BioSeal was not decoded
   * - -8024
     - NotSupported
     - Function or request not supported
   * - -8025
     - UnableToVerifyCertificateChain
     - Unable to verify the certificate chain
   * - -8026
     - NeedToVerify
     - Need to verify the BioSeal
   * - -8027
     - NoSignatureFound
     - No signature found
   * - -8028
     - FunctionNotImplemented
     - This function is not implemented
   * - -8029
     - NoCertificateFound
     - No certificate found
   * - -8030
     - InternalSslError
     - Internal SSL error
   * - -8031
     - UrlParsingError
     - Unable to parse the given URL
   * - -8032
     - UnsupportedDocumentIssuingCountry
     - Document issuing country not supported
   * - -8033
     - WrongPrefix
     - Incorrect issuing agency code (IAC) in code prefix
   * - -8034
     - DuplicateManifestField
     - Duplicate manifest field

License Error Codes
~~~~~~~~~~~~~~~~~~~

.. list-table:: 
   :header-rows: 1
   :widths: 10 20 50

   * - Code
     - Name
     - Description
   * - 0
     - Success
     - No error
   * - -1
     - InsufficientBuffer
     - The given buffer is too small
   * - -2
     - ObjectDoesNotExist
     - The requested object does not exist; a 'null' should be returned if possible
   * - -100
     - Base
     - Base error code of the License module
   * - -101
     - InvalidHandle
     - The handle is invalid
   * - -102
     - InvalidParameter
     - One of the parameters is incorrect
   * - -103
     - LicenseNotFound
     - No license was found
   * - -104
     - InvalidLicense
     - License is not valid or a required module is not licensed
   * - -105
     - ExpiredLicense
     - The license has expired
   * - -106
     - InvalidHardwareId
     - Installation code does not match hardware ID
   * - -107
     - AlreadyFulfilled
     - The license is already fulfilled by another user (or computer)
   * - -108
     - ModuleError
     - A required module is not licensed or the usage limit has been reached
   * - -109
     - WriteError
     - The license file cannot be accessed in write mode
   * - -110
     - InsufficientLicenseCredits
     - The number of available licenses has been reached
   * - -111
     - InvalidSerial
     - The serial is invalid
   * - -112
     - InvalidCredentials
     - Invalid login or password
   * - -113
     - RevokedLicense
     - The license is revoked or does not exist anymore
   * - -114
     - BlockedLicense
     - The license is blocked after a predefined period
   * - -115
     - UnreachableServer
     - The license server is currently unreachable
   * - -116
     - LicenseOtherError
     - An unexpected error happened
   * - -117
     - MissingFile
     - No license file was provided
   * - -118
     - DeviceNotCompatible
     - This device is not compatible with id3 licensing system
   * - -119
     - ActivationFailed
     - The activation of the license has failed
   * - -120
     - ServiceUnavailable
     - The license web services are unavailable
   * - -121
     - NotRenewable
     - The license is not renewable
   * - -122
     - DigestInvalid
     - The digest is invalid. The received file may be corrupted
   * - -123
     - ProductUnavailable
     - No credit available for this product
   * - -124
     - UnauthorizedAction
     - You are not allowed to do this
   * - -125
     - PreBlockedLicense
     - The license will be shortly blocked

See also
--------
- :ref:`id3_bioseal_bioseal_exception`
- :ref:`id3_bioseal_bioseal_error_enum`
