The Fees 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.

Fees Engine errors

The following errors can occur when interacting with the Fees 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	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-0035	Package amount range overlap	The maximumAmount and minimumAmount of the new package overlap with the amount range of an existing package.
FEE-0036	Invalid sort order	Invalid sort_order value. Expected 'asc' or 'desc'.
FEE-0037	Error to Distribute Values	Error to try distribute the values of Send object. Please check the data passed.
FEE-0038	Failed to apply rule: maxBetweenTypes	applicationRule maxBetweenTypes must have more than 1 calculation for Fee %v.
FEE-0039	Invalid segmentID	The specified segmentID is not a valid UUID. Please check the value passed.
FEE-0040	Invalid ledgerID	The specified ledgerID is not a valid UUID. Please check the value passed.
FEE-0041	Unmarshalling error	Invalid value for field '%s': expected type '%s', but got '%s'.
FEE-0042	Error to convert values	The value of the field %s is invalid. Remember to use dot (.) as decimal separator instead of comma (,). Example: use 1000.50 instead of 1000,50.
FEE-0043	originalAmount is required when isDeductibleFrom is true	For isDeductibleFrom `true`, referenceAmount must be ‘originalAmount' for '%s’.
FEE-0044	applicationRule invalid value	applicationRule is invalid, Err: %v.
FEE-0045	forbidden to access Midaz	Error to access Midaz. Please check the client credentials to access Midaz for creditAccount %v validation.
FEE-0046	calculation value percentage invalid	Calculation value is invalid can not utrapass 100%%. Please check the calculation value for Fee %v..
FEE-0047	calculation value flat invalid	Calculation value is invalid can not utrapass the minimum amount %v. Please check the calculation value for Fee %v.
FEE-0048	error to access Midaz	Error to access Midaz to validate creditAccount %v. Please check the client credentials to access Midaz.
FEE-0049	deductible value forbidden	Can not update deductible value to true. The calculation value is bigger than 100%% for Fee %v.
FEE-0050	deductible value forbidden	Can not update deductible value to true. Calculation value is bigger than the minimum amount %v for Fee %v.

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.