The Fee Engine returns consistent and structured error responses. This helps you quickly understand what went wrong and how to fix it.

Error Format

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

Field Definitions

code – A stable, unique identifier for the error. Useful for programmatic handling and support requests.
title – A short, human-readable summary of the issue.
message – Detailed guidance to help you resolve the error.

This structure ensures you always get actionable feedback when something doesn’t go as expected.

Fee Engine Errors

The following errors can occur when interacting with the Fee Engine endpoints. Each error follows our standard structure, making it easier to debug and respond to issues programmatically.

Refer to the table below for a list of possible error codes, what they mean, and how to resolve them.

400

Code	Title	Message
FEE-0001	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.
FEE-0002	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.
FEE-0003	Bad request	The server could not understand the request due to malformed syntax. Please check the listed fields and try again.
FEE-0005	Calculation field type invalid	The Calculation field type is invalid. Values can only be percentage or fixed.
FEE-0006	Invalid query parameter	One or more query parameters are in an incorrect format. Please check the following parameters 'parametros_erros' and ensure they meet the required format before trying again.
FEE-0007	Invalid date format error	The 'initialDate', 'finalDate', or both are in the incorrect format. Please use the 'yyyy-mm-dd' format and try again.
FEE-0008	Invalid final date error	The 'finalDate' cannot be earlier than the 'initialDate'. Please verify the dates and try again.
FEE-0009	Date range exceeds limit error	The range between 'initialDate' and 'finalDate' exceeds the permitted limit of %v months. Please adjust the dates and try again.
FEE-0010	Invalid date range error	Both 'initialDate' and 'finalDate' fields are required and must be in the 'yyyy-mm-dd' format. Please provide valid dates and try again.
FEE-0011	Pagination limit exceeded	The pagination limit exceeds the maximum allowed of %v items per page. Please verify the limit and try again.
FEE-0012	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.
FEE-0014	Account not found Midaz	Failed to find account on Midaz. Please check the credit account passed.
FEE-0015	minimumAmount greater than maximumAmount	minimumAmount value is greater than maximumAmount.
FEE-0016	Invalid path parameter	Path parameters is in an incorrect format. Please check the following parameter and ensure they meet the required format before trying again.
FEE-0018	Package already exists	There is a Package with same index values for [organizationId, ledgerId, segmentId, chartOfAccounts, minimumAmount, mininumAmountScale, maximumAmount, maximumAmountScale]
FEE-0019	Invalid header parameter	One or more headers parameters are in an incorrect format. Please check the following parameters and ensure they meet the required format before trying again.
FEE-0020	Missing header	Headers parameters is required. Please check the following header parameters %v and ensure they are passing the values correctly.
FEE-0022	Failed to calculate fee	Error to make the calculation of a fee about a transaction.
FEE-0023	Missing calculation model	The calculation model is required to Fee.
FEE-0024	originalAmount is required when priority is one	For Priority equals to one, referenceAmount must be 'originalAmount' for fee.
FEE-0025	Failed to apply rule: flatFee or percentual	applicationRule flatFee or percentual must have exactly 1 calculation for Fee.
FEE-0026	Invalid calculation type: percentual	The calculation type percentual must be 'percentage' for Fee.
FEE-0027	Invalid calculation type: flatFee	The calculation type flatFee must be 'flat' for Fee.
FEE-0028	Missing required fee fields	All fields of a new Fee must be filled. Please check again the payload passed.
FEE-0029	Calculation field is required for fee	Please fill the Calculation object correctly. All calculation fields must be filled.
FEE-0030	referenceAmount is not valid	Field reference amount must be originalAmount or afterFeesAmount.
FEE-0031	Invalid applicationRule	Field application rule must be maxBetweenTypes, flatFee or percentual.
FEE-0032	Error Calculation Type Invalid	Field calculation type must be percentage or flat.
FEE-0033	maximumAmount less than minimumAmount	maximumAmount value is less than minimumAmount.
FEE-0034	Invalid maximumAmountScale	The specified maximumAmountScale is not valid. It results in a maximumAmount that is less than the minimumAmount.
FEE-0035	Invalid minimumAmountScale	The specified minimumAmountScale is not valid. It results in a minimumAmount that is greater than the maximumAmount.
FEE-0036	Failed to find package amount data	The package does not contain amount data in the database.
FEE-0037	Package filtering error	Failed to filter a single package by chartOfAccount, segmentID, and maximum/minimum amount. Either no package was found or multiple packages matched the criteria.
FEE-0038	Package amount range overlap	The maximumAmount and minimumAmount of the new package overlap with the amount range of an existing package.
FEE-0039	Invalid sort order	Invalid sort_order value. Expected 'asc' or 'desc'.
FEE-0040	Error to Distribute Values	Error to try distribute the values of Send object. Please check the data passed.
FEE-0041	Failed to apply rule: maxBetweenTypes	applicationRule maxBetweenTypes must have more than 1 calculation for Fee %v.
FEE-0042	Invalid segmentID	The specified segmentID is not a valid UUID. Please check the value passed.
FEE-0043	Invalid ledgerID	The specified ledgerID is not a valid UUID. Please check the value passed.
FEE-0044	Unmarshalling error	invalid value for field '%s': expected type '%s', but got '%s'.

401

Code	Title	Message
FEE-0013	Invalid fee priority	The priority field in fees is invalid. Field can not be repeated.

403

Code	Title	Message
FEE-0017	Nothing to update	Fields not passed correctly. There is nothing to update.

500

Code	Title	Message
FEE-0004	Internal Server Error	The server encountered an unexpected error. Please try again later or contact support.

503

Code	Title	Message
FEE-0021	Invalid transaction type	Only one transaction type ('amount', 'share', or 'remaining') must be specified in the '%v' field for each entry. Please review your input and try again.