Handle API Errors

• A timeout as the third-party service is experiencing issues or is down.
• An improperly formatted request due to user error or a non-fatal software bug.
• A runtime error due to a system state or an “unexpected” error.

​

Error types

1. Non-HTTP errors
2. 4xx status codes
3. 500 status code

​

Non-HTTP errors

• Errors that prevent the execution of .js or .py (or any other extension) files such as command not found, or No such file or directory
• Errors relating to internal formatting of a file (missing indent, missing bracket, == instead of ===)
• Errors relating to system state, such as lack of memory, or network connectivity issues

​

Private key corruption

Error:  Error: error:1E08010C:DECODER routines::unsupported
    at Sign.sign (/myproject/lib/internal/crypto/sig.js:131:29)
    at Object.sign /myproject/node_modules/jwa/index.js:152:45)
    at Object.jwsSign [as sign] (/myproject/node_modules/jws/lib/sign-stream.js:32:24)
    at module.exports [as sign] (/myproject/node_modules/jsonwebtoken/sign.js:204:16)
    at ApiTokenProvider.signJwt (/myproject/fireblocks-sdk-js/src/api-token-provider.ts:11:28)
    at ApiClient.<anonymous> (/myproject/fireblocks-sdk-js/src/api-client.ts:15:41)
    at Generator.next (<anonymous>)
    at /myproject/fireblocks-sdk-js/dist/api-client.js:8:71
    at new Promise (<anonymous>)
    at __awaiter (/myproject/fireblocks-sdk-js/dist/api-client.js:4:12)
    at ApiClient.issueGetRequest (/myproject/fireblocks-sdk-js/dist/api-client.js:27:16)
    at FireblocksSDK.<anonymous> (/myproject/fireblocks-sdk-js/src/fireblocks-sdk.ts:537:37)
    at Generator.next (<anonymous>)
    at /myproject/fireblocks-sdk-js/dist/fireblocks-sdk.js:18:71
    at new Promise (<anonymous>)
    at __awaiter (/myproject/fireblocks-sdk-js/dist/fireblocks-sdk.js:14:12)

Traceback (most recent call last):
  File "/myproject/venv/lib/python3.10/site-packages/jwt/algorithms.py", line 257, in prepare_key
    key = load_pem_private_key(key, password=None)
  File "/myproject/venv/lib/python3.10/site-packages/cryptography/hazmat/primitives/serialization/base.py", line 22, in load_pem_private_key
    return ossl.load_pem_private_key(data, password)
  File "/myproject/venv/lib/python3.10/site-packages/cryptography/hazmat/backends/openssl/backend.py", line 900, in load_pem_private_key
    return self._load_key(
  File "/myproject/venv/lib/python3.10/site-packages/cryptography/hazmat/backends/openssl/backend.py", line 1168, in _load_key
    self._handle_key_loading_error()
  File "/myproject/venv/lib/python3.10/site-packages/cryptography/hazmat/backends/openssl/backend.py", line 1227, in _handle_key_loading_error
    raise ValueError(
ValueError: ('Could not deserialize key data. The data may be in an incorrect format, it may be encrypted with an unsupported algorithm, or it may be an unsupported key type (e.g. EC curves with explicit parameters).', [_OpenSSLErrorWithText(code=503841036, lib=60, reason=524556, reason_text=b'error:1E08010C:DECODER routines::unsupported')])

1. Verify that the file being used is indeed a private key. A private key typically looks like this:
   -----BEGIN PRIVATE KEY-----
              ...
   -----END PRIVATE KEY-----
   
2. Verify that the private key is intact.
3. Generate something out of the private key using OpenSSL. This command will attempt to convert the private key into its corresponding public key: openssl rsa -in <api-private-key>.key -pubout A valid response will look something like this:
   -----BEGIN PUBLIC KEY-----
               ...
   -----END PUBLIC KEY-----
   

​

4xx status codes

1. 400 - Bad request - Indicates that the API request itself is incorrect and contains invalid or incorrect values.
2. 401 - Unauthorized - Indicates that the API request is sent with invalid authentication information (for example, a bad JWT).
3. 403 - Forbidden - Indicates that the API request is trying to perform something the user is not allowed to do.
4. 404 - Not found - Indicates that the API request is trying to query a page that does not exist.

• The user input may not be valid, whether through a function call or direct integration.
• The network connection is functioning as expected.
• The system has sufficient resources (memory and disk space).

​

400 - Bad request

​

400 example - Bad request

const DEFAULT_VAULT_ACCOUNT_ID = "123";
/**
fbksSdk - an instance of FireblocksSDK
asset - the asset id
*/
async function getPublicKey(fbksSdk, asset){
  let pubKey = await fbks.getPublicKeyInfoForVaultAccount({
    vaultAccountId: DEFAULT_VAULT_ACCOUNT_ID,
    assetId:asset,
    compressed:true,
    addressIndex:"0",
    change:"0"
  });
  //... Some extra work on the public key ...
}

Error: Request failed with status code 400
    at createError (/myproject/fireblocks-sdk-js/node_modules/axios/lib/core/createError.js:16:15)
    at settle (/myproject/fireblocks-sdk-js/node_modules/axios/lib/core/settle.js:17:12)
    at IncomingMessage.handleStreamEnd (/myproject/fireblocks-sdk-js/node_modules/axios/lib/adapters/http.js:293:11)
    at IncomingMessage.emit (node:events:525:35)
    at endReadableNT (node:internal/streams/readable:1359:12)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)

Traceback (most recent call last):
  File "/myproject/main.py", line 10, in <module>
    get_public_key(fbksSdk, "jngjewqn")
  File "/myproject/main.py", line 8, in get_public_key
    fbks.get_public_key_info_for_vault_account(vault_account_id="2", asset_id=asset, compressed=False, change="0", address_index="0")
  File "/myproject/venv/lib/python3.10/site-packages/fireblocks_sdk/sdk.py", line 1066, in get_public_key_info_for_vault_account
    return self._get_request(url)
  File "/myproject/venv/lib/python3.10/site-packages/fireblocks_sdk/sdk.py", line 1334, in _get_request
    return handle_response(response, page_mode)
  File "/myproject/venv/lib/python3.10/site-packages/fireblocks_sdk/sdk.py", line 22, in handle_response
    raise FireblocksApiException("Got an error from fireblocks server: " + response.text, error_code)
fireblocks_sdk.api_types.FireblocksApiException:
  Got an error from fireblocks server: {
    "message":"The asset 'rando' is not supported by Fireblocks, please check the supported assets endpoint.",
    "code":1503
  }

const DEFAULT_VAULT_ACCOUNT_ID = "123";
/**
fbksSdk - an instance of FireblocksSDK
asset - the asset id
*/
async function getPublicKey(fbksSdk, asset){
  let pubKeyResponse = undefined;
  try{
    pubKeyResponse = await fbks.getPublicKeyInfoForVaultAccount({
      vaultAccountId: DEFAULT_VAULT_ACCOUNT_ID,
      assetId:asset,
      compressed:true,
      addressIndex:"0",
      change:"0"
    });
  } catch (e) {
    let response = e.response;
    if(response.status < 400 || response.status >= 500){
      	// Non request based error
      	// We assume that execution of this function will be halted after this block is done
    }

    let respData = response.data;
    if(respData.code === 1503){ // This is discussed later on in the article
      	return new Error("The asset you specified is invalid, please verify that you're sending the correct asset.");
    }

    // Other handling
  }
  //... Some extra work on the public key ...
}

​

Handling a 400 error

{
  error_code: number (optional)
  message: string
}

1. Identify the features/components you’re using - Are you performing wallet-specific operations (whitelisting, creating a new wallet, adding a deposit address to a wallet, etc.)?
2. Identify the user / system-provided inputs - What is constant? What is received as part of the system state (a database query, a read from a file, etc.)? What is received from user input?
3. Identify the potential errors from the API responses page.

​

Implementing 400 error handling

1. Refresh the balance of the specific asset they want to withdraw from the vault account assigned to this user - using the refresh asset balance data operation.
2. Create a transaction to send the asset from their vault account to the target address - using the create transaction operation.

1. The refresh asset balance data operation requires a valid vault account ID and a valid asset.
2. The create transaction operation requires:
   1. A valid asset (can be assumed valid after operation #1 takes place)
   2. A valid amount of said asset (which does not exceed what they have in the wallet)
   3. A valid target address

1. 1503 - invalid asset
2. 11001 - invalid vault account id

// Fireblocks SDK initialized beforehand and is defined as the parameter - fbks
// There exists some variable which allows us to query a database for information, defined as - dbSvc
async function withdrawal(userId, asset, amount, to){
    if(!dbSvc.userExists(userId)){
        return new Error(`Unknown user: ${userId}`);
    }
    if(!validateToAddress(to, asset)){
          return new Error("The address provided does not match conventions for the asset specified.");
    }
    // We assume that the information is stored somewhere you are able to retrieve it, but where it's stored is irrelevant, this is merely for the example
    let userVaultAccountId = dbSvc.getVaultAccountForUser(userId);
    let assetBalance = undefined;
    try{
        assetBalance = parseFloat((await fbks.refreshVaultAssetBalance(userVaultAccountId, asset)).available);
    } catch (e) {
        fbksError(e);
    }

    // At this point you might want to do additional checks against different information
    // in your system, depending on what your needs are.

    let txArgs = {
        source: {
            type: PeerType.VAULT_ACCOUNT,
            id: userVaultAccountId
        },
        destination: {
            type: PeerType.ONE_TIME_ADDRESS,
            oneTimeAddress: {
                address: to
            }
        },
        operation: TransactionOperation.TRANSFER,
        amount: amount,
        assetId: asset
    };

    try{
        let {txId: id} = (await fbks.createTransaction(txArgs));
        // Continue monitoring the transaction
    } catch (e) {
        fbksError(e);
    }
}

// This function is used as a generic error handler for all FireblocksAPI calls, preventing us from duplicating code and
// allowing us to easily fix issues in a single location. If a call requires custom handling, its catch clause can
// be written without using this function
function fbksError(e){
    let resp = e.response;
    if(resp !== 400) {
        // Handle other errors and return
    }

    let respData = resp.data;
    switch(respData.code){
        case 1503:
            throw new Error("The asset specified is invalid");
        case 11001:
            // In this scenario, since the vault account Id is stored in a local database, we might want to
            // show a different error or potentially raise an alert, depending on your needs.
            throw new Error("The vault account Id used is invalid");
        default:
            // If we didn't map the potential error code, it's important to write as much information
            // about the error as possible, that way we can patch the code with minimal replications or intrusive investigation
            logUnexpectedError(`Faced error: ${util.inspect(respData,false,null,true)} which is not mapped.`);
            throw new Error("Unexpected error - please try again later");
    }
}

1. Lines 4-6: Performs checks on the user. (This depends on your business logic.)
2. Lines 7-9: Performs validation of the to address. Using the asset, you’ll see the format of the address to expect. You’ll have to define this more thoroughly, however, there are libraries that already provide this functionality.
   1. Example: BTC SegWit will start with bc1, and EVM-based chains will be a 40-character hex (with 0x prefix and checksummed). You’ll have to define this more thoroughly, however, there are libraries that already provide this functionality.
3. Line 11: Get the vault account id for the user. Similar to #1 it depends on your business logic and specific setup.
4. Lines 13-17: Refresh the balance of the provided information (asset and vault account ID), using the try and catch you catch any exceptions, and send them to the generic API handler (this is also specific to your implementation, the way it’s described here might not be the correct way to handle it in your code). If there was an error, with one of the expected, we return some descriptive error message which can be changed to explain to the user what to do.
5. Lines 22-36: Build the withdrawal transaction.
6. Lines 39-43: Send the transaction. Refer to our generic handler for any error generated from creating the transaction.

​

401 - Unauthorized

1. Signing with a different user’s private key (e.g. signing with another API user’s key instead of yours)
2. Signing with the correct private key, but the incorrect User ID.

​

403 - Forbidden

​

404 - Not Found

1. Identify what’s missing - These errors usually happen with GET requests, more than with other HTTP methods, and those GET requests are usually no more than 3 different arguments (with some exceptions), to help you pinpoint which one is “incorrect”.
2. Address the missing data by either regenerating it using a new Fireblocks API call or raising an exception/error to notify upstream whoever sent this data.

• 1004 - No vault account by that Id

// Fireblocks SDK initialized beforehand and is defined as the parameter - fbks
// There exists some variable which allows us to query a database for information, defined as - dbSvc
async function sufficientAssets(userId){
    if(!dbSvc.userExists(userId)){
        return new Error(`Unknown user: ${userId}`);
    }
    // We assume that the information is stored somewhere you are able to retrieve it, but where it's stored is irrelevant, this is merely for the example
    let userVaultAccountId = dbSvc.getVaultAccountForUser(userId);
    try{
        let numberOfAssets = (await fbks.getVaultAccountById(userVaultAccountId)).assets.length;
        return numberOfAssets <= 10;
    } catch (e) {
        fbksError(e);
    }
}

// This function is used as a generic error handler for all FireblocksAPI calls, preventing us from duplicating code and
// allowing us to easily fix issues in a single location. If a call requires custom handling, its catch clause can
// be written without using this function
function fbksError(e){
    let resp = e.response;
    if(resp !== 400) {
        // Handle other errors and return
    }

    let respData = resp.data;
    switch(respData.code){
        case 1004:
            throw new UnknownVaultAccountIdError();
        default:
            // If we didn't map the potential error code, it's important to write as much information
            // about the error as possible, that way we can patch the code with minimal replications or intrusive investigation
            logUnexpectedError(`Faced error: ${util.inspect(respData,false,null,true)} which is not mapped.`);
            throw new Error("Unexpected error - please try again later");
    }
}

1. Lines 4-6: Check the existence of such a userId
2. Line 8: Finds the vault account correlated to this userId
   1. Let’s assume, in this case, that if no such vault account exists in your internal database, you need to add a new entry incrementing from the last added vault account id
3. Lines 9-14: Gets the vault account and counts the number of assets. Returns based on our previous explanation (at most 10). If there is an error, handle using the generic error handler. If there is an error code 1004, you’ll receive a specific type of error. This type of error, in our scenario, will generate a new vault account by something upstream from where the error occurred.

​

500 status code

1. Do not immediately attempt the request again.
2. Double-check the parameters you’re passing. One of them might not be formatted correctly, resulting in a failure in our backend.
3. Check the status page to see if there is an ongoing issue.
4. Open a Support ticket or reach out to Support on Slack to address the issue.

​

Common validations to perform

1. You received the value and can immediately perform validation on that value
2. You received the value but some additional data is required before performing the validation

• Asset validation - When getting an asset, always verify that the asset is indeed a supported one. More information can be found in the supported assets API reference.
• OTA validation - When using one-time address, which is received from the user themselves, ensure that the format of the address matches the format of the network.
  • For example, BTC SegWit will require an address starting with bc1 and complying with Bech32 formatting. EVMs will be a 40-character checksummed hex string with a prefix of 0x.
• Amount validation - In cases where you allow users to specify amounts, such as partial withdrawal uses, you’ll always need to:
  1. Get the current balance available for the user, either via an API call or via an internal ledger (depending on your business logic).
  2. Verify that the amount is a positive decimal value in the range of (0, retrieved balance] (excluding 0).
• Vault account validation - Ensure the vault account is a non-negative integer. You might want to add restrictions (both in your Transaction Authorization Policy and in your code, to prevent access to vault accounts you don’t want users to be able to access).