Error format
{
"title": "<error_title>",
"status": 400,
"detail": "<error_detail>",
"code": "<error_code>"
}
Field definitions
title– A short, human-readable summary of the issue.status– The HTTP status code.detail– Detailed guidance to help you resolve the error.code– A stable product code that uniquely identifies the error (e.g.,MTCH-0001). Useful for programmatic handling and support requests.errors– (optional) A list with field-level validation details.
Field-level error details
For issues specific to individual fields, anerrors array provides additional context.
Examples:
{
"title": "Bad Request",
"status": 400,
"detail": "The request body is invalid or malformed. Please verify the JSON format and try again.",
"code": "MTCH-0001",
"errors": [
{ "location": "body.context_id", "message": "context_id is a required field" }
]
}
{
"title": "Not Found",
"status": 404,
"detail": "The requested resource does not exist. Please verify the ID and try again.",
"code": "MTCH-0005"
}
General errors
These errors apply to all Matcher API endpoints. 400
code | title | detail |
|---|---|---|
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 | detail |
|---|---|---|
MTCH-0003 | Unauthorized | The request could not be authenticated. Please verify your credentials and try again. |
code | title | detail |
|---|---|---|
MTCH-0020 | Payment Required | The configured usage quota has been exceeded. Contact your account administrator. |
code | title | detail |
|---|---|---|
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. |
MTCH-0021 | Forbidden | Billing is suspended. Contact an administrator to restore access. |
code | title | detail |
|---|---|---|
MTCH-0005 | Not Found | The requested resource does not exist. Please verify the ID and try again. |
code | title | detail |
|---|---|---|
MTCH-0007 | Conflict | The request conflicts with the current state of the resource. Please verify and try again. |
code | title | detail |
|---|---|---|
MTCH-0010 | Request Entity Too Large | The uploaded file exceeds the maximum allowed size. Please reduce the file size and try again. |
code | title | detail |
|---|---|---|
MTCH-0006 | Unprocessable Entity | The request was well-formed but could not be processed. Please verify the input data and try again. |
code | title | detail |
|---|---|---|
MTCH-0009 | Too Many Requests | The request rate limit has been exceeded. Please wait before retrying. |
code | title | detail |
|---|---|---|
MTCH-0002 | Internal Server Error | An unexpected error occurred. Please try again later or contact support if the issue persists. |
code | title | detail |
|---|---|---|
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
Matcher returns these errors for a problem in the reconciliation configuration (contexts, sources, field maps, match rules, fee rules, schedules). 400
code | title | detail |
|---|---|---|
MTCH-0109 | Bad Request | A context name is required. Please provide a valid name and try again. |
code | title | detail |
|---|---|---|
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 | detail |
|---|---|---|
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. |
MTCH-0118 | Conflict | This match rule cannot be deleted because a confirmed match group it created still has an exception attached. Change the rule configuration instead. |
Discovery errors
Matcher returns these errors for data source discovery and connection management. Discovery relies on Matcher’s embedded extraction engine — see Discovery for how it works. 400
code | title | detail |
|---|---|---|
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 | detail |
|---|---|---|
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 | detail |
|---|---|---|
MTCH-0205 | Conflict | A discovery refresh is already in progress. Please wait for it to complete before starting a new one. |
MTCH-0209 | Conflict | The connection was retired locally, but deletion could not be confirmed on the external system. Check whether it is still live there. |
code | title | detail |
|---|---|---|
MTCH-0210 | Unprocessable Entity | Matcher cannot run connectivity tests for this aggregator vendor yet; no test ran and nothing changed. |
code | title | detail |
|---|---|---|
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
Matcher returns these errors for transaction file upload and processing. 400
code | title | detail |
|---|---|---|
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 | detail |
|---|---|---|
MTCH-0319 | Forbidden | Document extraction is not enabled for this tenant. Please contact support to opt in. |
code | title | detail |
|---|---|---|
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 | detail |
|---|---|---|
MTCH-0311 | Request Timeout | The upload stalled because no data was received within the allowed time. Please retry the upload. |
code | title | detail |
|---|---|---|
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 | detail |
|---|---|---|
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 | detail |
|---|---|---|
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
Matcher returns these errors for the reconciliation matching process. 400
code | title | detail |
|---|---|---|
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 | detail |
|---|---|---|
MTCH-0409 | Forbidden | Rule suggestion is not enabled for this tenant. Please contact support to opt in. |
code | title | detail |
|---|---|---|
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 | detail |
|---|---|---|
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 | detail |
|---|---|---|
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
Matcher returns these errors for exception handling, disputes, and callback processing. 404
code | title | detail |
|---|---|---|
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. |
MTCH-0512 | Not Found | The resolution was applied, but Matcher could not confirm the exception’s updated record. Reload the exception to see its current status. |
code | title | detail |
|---|---|---|
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. |
MTCH-0510 | Conflict | A settlement is already in progress on this break. Retry the request once it completes. |
MTCH-0511 | Conflict | This exception is already resolved, so no further comments can be added. |
code | title | detail |
|---|---|---|
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 | detail |
|---|---|---|
MTCH-0513 | Bad Gateway | The target system rejected the dispatch, so no target record was created. Check the connector credentials and target project or queue before dispatching again. |
MTCH-0514 | Bad Gateway | The dispatch could not be confirmed, so a target record may already exist. Check the target before dispatching again. |
code | title | detail |
|---|---|---|
MTCH-0506 | Too Many Requests | The callback rate limit has been exceeded. Please wait before retrying. |
Governance errors
Matcher returns these errors for audit log and governance operations. 404
code | title | detail |
|---|---|---|
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
Matcher returns these errors for report export operations. 400
code | title | detail |
|---|---|---|
MTCH-0705 | Bad Request | The specified export format is invalid. Please verify the format and try again. |
code | title | detail |
|---|---|---|
MTCH-0701 | Not Found | The specified export job was not found. Please verify the job ID and try again. |
code | title | detail |
|---|---|---|
MTCH-0703 | Conflict | The export is not yet ready for download. Please wait for the export to complete. |
code | title | detail |
|---|---|---|
MTCH-0704 | Gone | The export has expired and is no longer available. Please create a new export request. |
code | title | detail |
|---|---|---|
MTCH-0702 | Service Unavailable | The export worker is currently disabled. Please contact support to enable it. |
Idempotency errors
Matcher returns these errors for a problem with idempotency key handling. 400
code | title | detail |
|---|---|---|
MTCH-0015 | Bad Request | The idempotency key must contain 1 to 128 letters, digits, hyphens, underscores, or colons; no request was processed. An empty key is also rejected. |
code | title | detail |
|---|---|---|
MTCH-0018 | Conflict | A request with this idempotency key is already being processed. Wait for it to complete, then retry with the same key; the original request may still succeed. |
code | title | detail |
|---|---|---|
MTCH-0016 | Internal Server Error | An unexpected error occurred. |
MTCH-0017 | Internal Server Error | Idempotency processing is temporarily unavailable; retry the same request later with the same idempotency key. If the failure continues, ask an administrator to check idempotency storage. |