Lista de erros do Matcher

Formato de erro

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

Definições de campos

code – Um código de produto estável que identifica de forma única o erro (ex., MTCH-0001). Útil para tratamento programático e solicitações de suporte.
title – Um resumo curto e legível do problema.
message – Orientação detalhada para ajudá-lo a resolver o erro.
details – (opcional) Um objeto estruturado com contexto adicional, como erros de validação a nível de campo.

Essa estrutura garante que você sempre receba feedback acionável quando algo não sair como esperado.

Detalhes de erro a nível de campo

Para problemas específicos de campos individuais, um objeto details fornece contexto adicional. Exemplos:

{
  "code": "MTCH-0001",
  "title": "Bad Request",
  "message": "The request body is invalid or malformed. Please verify the JSON format and try again.",
  "details": {
    "context_id": "context_id is a required field"
  }
}

{
  "code": "MTCH-0005",
  "title": "Not Found",
  "message": "The requested resource does not exist. Please verify the ID and try again."
}

Erros gerais

Esses erros se aplicam a todos os endpoints da API do Matcher. 400

`code`	`title`	`message`
`MTCH-0001`	Bad Request	The request body is invalid or malformed. Please verify the request format and try again.
`MTCH-0011`	Bad Request	The request failed. Please verify the request and try again.
`MTCH-0013`	Bad Request	The context ID is invalid. Please verify the ID format and try again.

401

`code`	`title`	`message`
`MTCH-0003`	Unauthorized	The request could not be authenticated. Please verify your credentials and try again.

403

`code`	`title`	`message`
`MTCH-0004`	Forbidden	You do not have permission to perform this action. Please verify your access level.
`MTCH-0012`	Forbidden	The reconciliation context is not active. Please activate the context before performing this operation.

404

`code`	`title`	`message`
`MTCH-0005`	Not Found	The requested resource does not exist. Please verify the ID and try again.

409

`code`	`title`	`message`
`MTCH-0007`	Conflict	The request conflicts with the current state of the resource. Please verify and try again.

413

`code`	`title`	`message`
`MTCH-0010`	Request Entity Too Large	The uploaded file exceeds the maximum allowed size. Please reduce the file size and try again.

422

`code`	`title`	`message`
`MTCH-0006`	Unprocessable Entity	The request was well-formed but could not be processed. Please verify the input data and try again.

429

`code`	`title`	`message`
`MTCH-0009`	Too Many Requests	The request rate limit has been exceeded. Please wait before retrying.

500

`code`	`title`	`message`
`MTCH-0002`	Internal Server Error	An unexpected error occurred. Please try again later or contact support if the issue persists.

503

`code`	`title`	`message`
`MTCH-0008`	Service Unavailable	A required service is temporarily unavailable. Please try again later.
`MTCH-0019`	Service Unavailable	Object storage is temporarily unavailable. Please try again later.

Erros de configuração

Esses erros são retornados quando há um problema com a configuração de conciliação (contextos, fontes, mapas de campos, regras de correspondência, regras de tarifas, agendamentos). 400

`code`	`title`	`message`
`MTCH-0109`	Bad Request	A context name is required. Please provide a valid name and try again.

404

`code`	`title`	`message`
`MTCH-0110`	Not Found	The specified context was not found. Please verify the context ID and try again.
`MTCH-0111`	Not Found	The specified source was not found. Please verify the source ID and try again.
`MTCH-0112`	Not Found	The specified field map was not found. Please verify the field map ID and try again.
`MTCH-0113`	Not Found	The specified match rule was not found. Please verify the match rule ID and try again.
`MTCH-0114`	Not Found	The specified fee rule was not found. Please verify the fee rule ID and try again.
`MTCH-0115`	Not Found	The specified fee schedule was not found. Please verify the fee schedule ID and try again.
`MTCH-0116`	Not Found	The specified schedule was not found. Please verify the schedule ID and try again.

409

`code`	`title`	`message`
`MTCH-0101`	Conflict	A context with this name already exists. Please choose a different name and try again.
`MTCH-0102`	Conflict	A resource with this priority already exists. Please choose a different priority value and try again.
`MTCH-0103`	Conflict	The resource is in an invalid state for this operation. Please verify its current state and try again.
`MTCH-0104`	Conflict	The context has been archived. Please use an active context for this operation.
`MTCH-0105`	Conflict	This resource cannot be deleted because it has an associated field map. Please remove the field map first.
`MTCH-0106`	Conflict	This resource cannot be deleted because it has dependent resources. Please remove the dependent resources first.
`MTCH-0107`	Conflict	A resource with this priority already exists. Please choose a different priority value.
`MTCH-0108`	Conflict	The fee schedule is currently in use and cannot be modified or deleted.
`MTCH-0117`	Conflict	This resource cannot be deleted because it has associated transactions. Please remove the transactions first.

Erros de descoberta

Esses erros são retornados durante a descoberta de fontes de dados e o gerenciamento de conexões. O Discovery depende do Fetcher, o serviço interno de extração de dados da Lerian — veja Discovery para entender como funciona. 400

`code`	`title`	`message`
`MTCH-0204`	Bad Request	The extraction request is invalid. Please verify the parameters and try again.
`MTCH-0208`	Bad Request	The specified connector type is not registered on this deployment. Please verify the connector type and try again.

404

`code`	`title`	`message`
`MTCH-0201`	Not Found	The specified connection was not found. Please verify the connection ID and try again.
`MTCH-0202`	Not Found	The specified extraction was not found. Please verify the extraction ID and try again.

409

`code`	`title`	`message`
`MTCH-0205`	Conflict	A discovery refresh is already in progress. Please wait for it to complete before starting a new one.

503

`code`	`title`	`message`
`MTCH-0203`	Service Unavailable	The Fetcher service is temporarily unavailable. Please try again later.
`MTCH-0206`	Service Unavailable	The connector’s data for the requested day has not been validated yet. Please try again later.
`MTCH-0207`	Service Unavailable	The connector’s report did not complete within the allotted time. Please try again later.

Erros de ingestão

Esses erros são retornados durante o upload e processamento de arquivos de transações. 400

`code`	`title`	`message`
`MTCH-0303`	Bad Request	The file format is required. Please specify the format and try again.
`MTCH-0304`	Bad Request	The uploaded file is empty. Please provide a non-empty file and try again.
`MTCH-0307`	Bad Request	The file was well-formed but contained no record elements to ingest. Please verify the file content and try again.
`MTCH-0308`	Bad Request	The uploaded file schema is not supported. Please verify the file structure and try again.
`MTCH-0317`	Bad Request	A mapping sample is required. Please provide a sample and try again.
`MTCH-0322`	Bad Request	The document body is empty. Please provide a non-empty document and try again.

403

`code`	`title`	`message`
`MTCH-0319`	Forbidden	Document extraction is not enabled for this tenant. Please contact support to opt in.

404

`code`	`title`	`message`
`MTCH-0301`	Not Found	The specified ingestion source was not found. Please verify the source ID and try again.
`MTCH-0302`	Not Found	The specified ingestion field map was not found. Please verify the field map ID and try again.
`MTCH-0306`	Not Found	The specified ingestion job was not found. Please verify the job ID and try again.

408

`code`	`title`	`message`
`MTCH-0311`	Request Timeout	The upload stalled because no data was received within the allowed time. Please retry the upload.

409

`code`	`title`	`message`
`MTCH-0305`	Conflict	The ingestion job is in an invalid state for this operation. Please verify its current state.
`MTCH-0324`	Conflict	The extraction review is no longer pending and cannot be modified. Please verify its current state.

422

`code`	`title`	`message`
`MTCH-0309`	Unprocessable Entity	The ingestion job exceeded the configured error rate threshold. Please review the source data and try again.
`MTCH-0310`	Unprocessable Entity	The source configuration is invalid. Please fix the source configuration and retry the upload.
`MTCH-0312`	Unprocessable Entity	The source’s field map is invalid. Please fix the field map and retry the upload.
`MTCH-0321`	Unprocessable Entity	No transaction candidates could be extracted from the document. Please verify the document and try again.

503

`code`	`title`	`message`
`MTCH-0313`	Service Unavailable	Fetch-and-ingest is not enabled on this deployment. Please upload the file manually.
`MTCH-0314`	Service Unavailable	The external transport could not be reached or read. Please try again later.
`MTCH-0315`	Service Unavailable	Mapping proposal is not enabled on this deployment. Please configure the field map manually.
`MTCH-0316`	Service Unavailable	The mapping advisor is unavailable. Please configure a field map manually.
`MTCH-0318`	Service Unavailable	Document extraction is not enabled on this deployment. Please ingest the file manually.
`MTCH-0320`	Service Unavailable	The document extractor is unavailable. Please ingest the file manually.
`MTCH-0323`	Service Unavailable	Extraction review is not enabled on this deployment. Please try again later.

Erros de correspondência

Esses erros são retornados durante o processo de correspondência de conciliação. 400

`code`	`title`	`message`
`MTCH-0401`	Bad Request	No sources are configured for this context. Please configure at least one source before running a match.
`MTCH-0402`	Bad Request	At least two sources are required for matching. Please configure additional sources.
`MTCH-0403`	Bad Request	Each source must have a defined side. Please specify the source side and try again.
`MTCH-0404`	Bad Request	The one-to-one topology configuration is invalid. Please verify the source configuration.
`MTCH-0405`	Bad Request	The one-to-many topology configuration is invalid. Please verify the source configuration.

403

`code`	`title`	`message`
`MTCH-0409`	Forbidden	Rule suggestion is not enabled for this tenant. Please contact support to opt in.

409

`code`	`title`	`message`
`MTCH-0408`	Conflict	A matching run is already in progress for this context. Please wait for it to complete.
`MTCH-0413`	Conflict	The suggestion is no longer pending and cannot be modified. Please verify its current state.

422

`code`	`title`	`message`
`MTCH-0406`	Unprocessable Entity	Fee rules are required but not configured. Please add fee rules before running a match.
`MTCH-0407`	Unprocessable Entity	Fee rules are misconfigured. Please review the fee rule settings and try again.
`MTCH-0412`	Unprocessable Entity	The approved suggestion failed validation. Please review the suggestion and try again.

503

`code`	`title`	`message`
`MTCH-0410`	Service Unavailable	Rule suggestion is not enabled on this deployment. Please author match rules manually.
`MTCH-0411`	Service Unavailable	The rule advisor is unavailable. Please author match rules manually.

Erros de exceção

Esses erros são retornados durante o tratamento de exceções, disputas e processamento de callbacks. 404

`code`	`title`	`message`
`MTCH-0501`	Not Found	The specified exception was not found. Please verify the exception ID and try again.
`MTCH-0502`	Not Found	The specified dispute was not found. Please verify the dispute ID and try again.
`MTCH-0507`	Not Found	The specified comment was not found. Please verify the comment ID and try again.

409

`code`	`title`	`message`
`MTCH-0504`	Conflict	A callback for this exception is already being processed. Please wait for it to complete.
`MTCH-0505`	Conflict	The callback encountered a transient error and can be retried. Please retry the request.

422

`code`	`title`	`message`
`MTCH-0503`	Unprocessable Entity	The exception is in an invalid state for this operation. Please verify its current state.
`MTCH-0508`	Unprocessable Entity	The dispatch target type is not supported. Please verify the target configuration.
`MTCH-0509`	Unprocessable Entity	The dispatch connector is not configured. Please configure the connector and try again.

429

`code`	`title`	`message`
`MTCH-0506`	Too Many Requests	The callback rate limit has been exceeded. Please wait before retrying.

Erros de governança

Esses erros são retornados durante operações de log de auditoria e governança. 404

`code`	`title`	`message`
`MTCH-0601`	Not Found	The specified audit log was not found. Please verify the audit log ID and try again.
`MTCH-0602`	Not Found	The specified actor mapping was not found. Please verify the actor mapping ID and try again.
`MTCH-0603`	Not Found	The specified archive was not found. Please verify the archive ID and try again.

Erros de relatórios

Esses erros são retornados durante operações de exportação de relatórios. 400

`code`	`title`	`message`
`MTCH-0705`	Bad Request	The specified export format is invalid. Please verify the format and try again.

404

`code`	`title`	`message`
`MTCH-0701`	Not Found	The specified export job was not found. Please verify the job ID and try again.

409

`code`	`title`	`message`
`MTCH-0703`	Conflict	The export is not yet ready for download. Please wait for the export to complete.

410

`code`	`title`	`message`
`MTCH-0704`	Gone	The export has expired and is no longer available. Please create a new export request.

503

`code`	`title`	`message`
`MTCH-0702`	Service Unavailable	The export worker is currently disabled. Please contact support to enable it.

Erros de idempotência

Esses erros são retornados quando há um problema com o tratamento de chaves de idempotência. 400

`code`	`title`	`message`
`MTCH-0015`	Bad Request	The provided idempotency key is invalid. Please verify the key format and try again.

409

`code`	`title`	`message`
`MTCH-0018`	Conflict	A request with this idempotency key is currently being processed. Please wait for it to complete before retrying.

500

`code`	`title`	`message`
`MTCH-0016`	Internal Server Error	The idempotency configuration is invalid. Please contact support if the issue persists.
`MTCH-0017`	Internal Server Error	An unexpected error occurred while processing the idempotency key. Please try again later.

Emitir um token de webhook de agregador

​Formato de erro

​Definições de campos

​Detalhes de erro a nível de campo

​Erros gerais

​Erros de configuração

​Erros de descoberta

​Erros de ingestão

​Erros de correspondência

​Erros de exceção

​Erros de governança

​Erros de relatórios

​Erros de idempotência

Formato de erro

Definições de campos

Detalhes de erro a nível de campo

Erros gerais

Erros de configuração

Erros de descoberta

Erros de ingestão

Erros de correspondência

Erros de exceção

Erros de governança

Erros de relatórios

Erros de idempotência