Error format
{
"code": "<error_code>",
"title": "<error_title>",
"message": "<error_message>"
}
Field definitions
code– A stable product code that uniquely identifies the error (e.g.,MTCH-0001). 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.details– (optional) A structured object with additional context, such as field-level validation errors.
Field-level error details
For issues specific to individual fields, adetails object provides additional context.
Examples:
{
"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."
}
General errors
These errors apply to all Matcher API endpoints. 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. |
code | title | message |
|---|---|---|
MTCH-0003 | Unauthorized | The request could not be authenticated. Please verify your credentials and try again. |
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. |
code | title | message |
|---|---|---|
MTCH-0005 | Not Found | The requested resource does not exist. Please verify the ID and try again. |
code | title | message |
|---|---|---|
MTCH-0007 | Conflict | The request conflicts with the current state of the resource. Please verify and try again. |
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. |
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. |
code | title | message |
|---|---|---|
MTCH-0009 | Too Many Requests | The request rate limit has been exceeded. Please wait before retrying. |
code | title | message |
|---|---|---|
MTCH-0002 | Internal Server Error | An unexpected error occurred. Please try again later or contact support if the issue persists. |
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. |
Configuration errors
These errors are returned when there is an issue with the reconciliation configuration (contexts, sources, field maps, match rules, fee rules, schedules). 400
code | title | message |
|---|---|---|
MTCH-0109 | Bad Request | A context name is required. Please provide a valid name and try again. |
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. |
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. |
Discovery errors
These errors are returned during data source discovery and connection management. Discovery relies on Fetcher, Lerian’s internal data-extraction service — see Discovery for how it works. 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. |
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. |
code | title | message |
|---|---|---|
MTCH-0205 | Conflict | A discovery refresh is already in progress. Please wait for it to complete before starting a new one. |
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. |
Ingestion errors
These errors are returned during transaction file upload and processing. 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. |
code | title | message |
|---|---|---|
MTCH-0319 | Forbidden | Document extraction is not enabled for this tenant. Please contact support to opt in. |
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. |
code | title | message |
|---|---|---|
MTCH-0311 | Request Timeout | The upload stalled because no data was received within the allowed time. Please retry the upload. |
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. |
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. |
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. |
Matching errors
These errors are returned during the reconciliation matching process. 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. |
code | title | message |
|---|---|---|
MTCH-0409 | Forbidden | Rule suggestion is not enabled for this tenant. Please contact support to opt in. |
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. |
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. |
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. |
Exception errors
These errors are returned during exception handling, disputes, and callback processing. 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. |
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. |
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. |
code | title | message |
|---|---|---|
MTCH-0506 | Too Many Requests | The callback rate limit has been exceeded. Please wait before retrying. |
Governance errors
These errors are returned during audit log and governance operations. 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. |
Reporting errors
These errors are returned during report export operations. 400
code | title | message |
|---|---|---|
MTCH-0705 | Bad Request | The specified export format is invalid. Please verify the format and try again. |
code | title | message |
|---|---|---|
MTCH-0701 | Not Found | The specified export job was not found. Please verify the job ID and try again. |
code | title | message |
|---|---|---|
MTCH-0703 | Conflict | The export is not yet ready for download. Please wait for the export to complete. |
code | title | message |
|---|---|---|
MTCH-0704 | Gone | The export has expired and is no longer available. Please create a new export request. |
code | title | message |
|---|---|---|
MTCH-0702 | Service Unavailable | The export worker is currently disabled. Please contact support to enable it. |
Idempotency errors
These errors are returned when there is an issue with idempotency key handling. 400
code | title | message |
|---|---|---|
MTCH-0015 | Bad Request | The provided idempotency key is invalid. Please verify the key format and try again. |
code | title | message |
|---|---|---|
MTCH-0018 | Conflict | A request with this idempotency key is currently being processed. Please wait for it to complete before retrying. |
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. |