Errors list

Here you can find the list with all the errors that you might face throughout the API integration with Midaz.

---

API Error Codes Reference

When working with our API, you might encounter certain error responses. These errors are designed to help you quickly understand and troubleshoot issues.

Error structure

Our error messages will have the same structure as follows:

{
   "code":"<error_code>",
   "title":"<error_title>",
   "message":"<error_message>"
}

Fields object

In cases where there is a need to provide additional information about specific fields, the fields object will also be displayed, including the name of the field causing the error and the reason.

Examples:

0009

{
   "code":"0009",
   "title":"Missing Fields in Request",
   "message":"Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.",
   "fields": {
      "{{field}}": "{{field}} is a required field"
   }
}

0047

{
   "code":"0047",
   "title":"Bad Request",
   "message":"The server could not understand the request due to malformed syntax. Please check the listed fields and try again.",
   "fields":{
      "legalName": "legalName is a required field.",
      "parentOrganizationId":"parentOrganizationId must be a valid UUID"
   }
}

0053

{
   "code":"0053",
   "title":"Unexpected Fields in the Request",
   "message":"The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.",
   "fields":{
      "{{field}}":"{{error_message}}"
   }
}

Attributes

Name	Type	Description
code	String	The error code.
title	String	The title of the error.
message	String	A description with more information about the error.
fields	Object	A list of the names of the fields that are throwing the error and the reason why. NOTE: Used in the Missing Fields in Request ("code":"0009"), Bad Requests ("code":"0047") and Unexpected Fields in the Requests ("code":"0053") errors.

Error integration

When integrating, always use the code field, not the title and message fields, as the code field remains constant while the others can change. For more information, refer to the Error handling page.

Code details

The table below provides a list of potential error codes and their respective titles and descriptions to assist you in the integration process.

Code	Title	Message
0001	Duplicate Ledger Error	A ledger with the name {{name}} already exists in the division {{divisionName}}. Please rename the ledger or choose a different division to attach it to.
0002	Ledger Name Conflict	A ledger named {{name}} already exists in your organization. Please rename the ledger, or if you want to use the same name, consider creating a new ledger for a different division.
0003	Asset Name or Code Duplicate	An asset with the same name or code already exists in your ledger. Please modify the name or code of your new asset.
0004	Code Uppercase Requirement	The code must be in uppercase. Please ensure that the code is in uppercase format and try again.
0005	Currency Code Standard Compliance	Currency-type assets must comply with the ISO-4217 standard. Please use a currency code that conforms to ISO-4217 guidelines.
0006	Unmodifiable Field Error	Your request includes a field that cannot be modified. Please review your request and try again, removing any uneditable fields. Please refer to the documentation for guidance.
0007	Entity Not Found	No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage.
0008	Action Not Permitted	The action you are attempting is not allowed in the current environment. Please refer to the documentation for guidance.
0009	Missing Fields in Request	Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.
0010	Account Type Immutable	The account type specified cannot be modified. Please ensure the correct account type is being used and try again.
0011	Inactive Account Type Error	The account type specified cannot be set to INACTIVE. Please ensure the correct account type is being used and try again.
0012	Account Balance Deletion Error	An account or sub-account cannot be deleted if it has a remaining balance. Please ensure all remaining balances are transferred to another account before attempting to delete.
0013	Resource Already Deleted	The resource you are trying to delete has already been deleted. Ensure you are using the correct ID and try again.
0014	Product ID Inactive	The Product ID you are attempting to use is inactive. Please use another Product ID and try again.
0015	Duplicate Product Name Error	A product with the name {{name}} already exists for this ledger ID {{ledgerId}}. Please try again with a different ledger or name.
0016	Balance Remaining Deletion Error	The asset cannot be deleted because there is a remaining balance. Please ensure all balances are cleared before attempting to delete again.
0017	Invalid Script Format Error	The script provided in your request is invalid or in an unsupported format. Please verify the script format and try again.
0018	Insufficient Funds Error	The transaction could not be completed due to insufficient funds in the account. Please add sufficient funds to your account and try again.
0019	Account Ineligibility Error	One or more accounts listed in the transaction are not eligible to participate. Please review the account statuses and try again.
0020	Alias Unavailability Error	The alias {{alias}} is already in use. Please choose a different alias and try again.
0021	Parent Transaction ID Not Found	The parentTransactionId {{parentTransactionId}} does not correspond to any existing transaction. Please review the ID and try again.
0022	Immutable Field Error	The {{field}} field cannot be modified. Please remove this field from your request and try again.
0023	Transaction Timing Restriction	You can only perform another transaction using {{assetCode}} of {{amount}} from {{source}} to {{destination}} after {{timestampUnlock}}. Please wait until the specified time to try again.
0024	Account Status Transaction Restriction	The current statuses of the source and/or destination accounts do not permit transactions. Change the account status(es) and try again.
0025	Insufficient Account Balance Error	The account {{accountId}} does not have sufficient balance. Please try again with an amount that is less than or equal to the available balance.
0026	Transaction Method Restriction	Transactions involving {{assetCode}} are not permitted for the specified source and/or destination. Please try again using accounts that allow transactions with {{assetCode}}.
0027	Duplicate Transaction Template Code Error	A transaction template with the code {{code}} already exists for your ledger. Please use a different code and try again.
0028	Duplicate Asset Pair Error	A pair for the assets {{baseAssetCode}}{{counterAssetCode}} already exists with the ID {{asset_rates.id}}. Please update the existing entry instead of creating a new one.
0029	Invalid Parent Account ID	The specified parent account ID does not exist. Please verify the ID is correct and try your request again.
0030	Mismatched Asset Code	The parent account ID you provided is associated with a different asset code than the one specified in your request. Please make sure the asset code matches that of the parent account, or use a different parent account ID and try again.
0031	Chart Type Not Found	The chart type {{chartType}} does not exist. Please provide a valid chart type and refer to the documentation if you have any questions.
0032	Invalid Country Code	The provided country code in the 'address.country' field does not conform to the ISO-3166 alpha-2 standard. Please provide a valid alpha-2 country code.
0033	Invalid Code Format	The 'code' field must be alphanumeric, in upper case, and must contain at least one letter. Please provide a valid code.
0034	Asset Code Not Found	The provided asset code does not exist in our records. Please verify the asset code and try again.
0035	Portfolio ID Not Found	The provided portfolio ID does not exist in our records. Please verify the portfolio ID and try again.
0036	Product ID Not Found	The provided product ID does not exist in our records. Please verify the product ID and try again.
0037	Ledger ID Not Found	The provided ledger ID does not exist in our records. Please verify the ledger ID and try again.
0038	Organization ID Not Found	The provided organization ID does not exist in our records. Please verify the organization ID and try again.
0039	Parent Organization ID Not Found	The provided parent organization ID does not exist in our records. Please verify the parent organization ID and try again.
0040	Invalid Type	The provided 'type' is not valid. Accepted types are currency, crypto, commodities, or others. Please provide a valid type.
0041	Token Missing	A valid token must be provided in the request header. Please include a token and try again.
0042	Invalid Token	The provided token is expired, invalid or malformed. Please provide a valid token and try again.
0043	Insufficient Privileges	You do not have the necessary permissions to perform this action. Please contact your administrator if you believe this is an error.
0044	Permission Enforcement Error	The enforcer is not configured properly. Please contact your administrator if you believe this is an error.
0045	JWK Fetch Error	The JWK keys could not be fetched from the source. Please verify the source environment variable configuration and try again.
0046	Internal Server Error	The server encountered an unexpected error. Please try again later or contact support.
0047	Bad Request	The server could not understand the request due to malformed syntax. Please check the listed fields and try again.
0048	Invalid DSL File Format	The submitted DSL file {{fileName}} is in an incorrect format. Please ensure that the file follows the expected structure and syntax.
0049	Empty DSL File	The submitted DSL file {{fileName}} is empty. Please provide a valid file with content.
0050	Metadata Key Length Exceeded	The metadata key {{key}} exceeds the maximum allowed length of 100 characters. Please use a shorter key.
0051	Metadata Value Length Exceeded	The metadata value {{value}} exceeds the maximum allowed length of 100 characters. Please use a shorter value.
0052	Account ID Not Found	The provided account ID does not exist in our records. Please verify the account ID and try again.
0053	Unexpected Fields in the Request	The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.
0054	IDs Not Found for Accounts	No accounts were found for the provided IDs. Please verify the IDs and try again.
0055	Asset ID Not Found	The provided asset ID does not exist in our records. Please verify the asset ID and try again.
0056	No Assets Found	No assets were found in the search. Please review the search criteria and try again.
0057	No Products Found	No products were found in the search. Please review the search criteria and try again.
0058	No Portfolios Found	No portfolios were found in the search. Please review the search criteria and try again.
0059	No Organizations Found	No organizations were found in the search. Please review the search criteria and try again.
0060	No Ledgers Found	No ledgers were found in the search. Please review the search criteria and try again.
0061	Balance Update Failed	The balance could not be updated for the specified account ID. Please verify the account ID and try again.
0062	No Account IDs Provided	No account IDs were provided for the balance update. Please provide valid account IDs and try again.
0063	Failed To Retrieve Accounts By Aliases	The accounts could not be retrieved using the specified aliases. Please verify the aliases for accuracy and try again.
0064	No Accounts Found	No accounts were found in the search. Please review the search criteria and try again.
0065	Invalid Path Parameter	The provided path parameter {{parameter_name}} is not in the expected format. Please ensure the parameter adheres to the required format and try again.
0066	Invalid Account Type	The provided 'type' is not valid. Accepted types are: deposit, savings, loans, marketplace, creditCard or external. Please provide a valid type.
0067	Invalid Metadata Nesting	The metadata object cannot contain nested values. Please ensure that the value {{value}} is not nested and try again.