> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Matcher error list
> Matcher APIs return a structured error object for all errors to simplify issue diagnosis.
### Error format
```json JSON theme={null}
{
"code": "",
"title": "",
"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.
This structure ensures you always get actionable feedback when something doesn't go as expected.
### Field-level error details
For issues specific to individual fields, a `details` object provides additional context.
Examples:
```json Example 1 theme={null}
{
"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"
}
}
```
```json Example 2 theme={null}
{
"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. |
**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. |
## 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. |
**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. |
## Discovery errors
***
These errors are returned during data source discovery and connection management.
**400**
| `code` | `title` | `message` |
| ----------- | ----------- | ------------------------------------------------------------------------------ |
| `MTCH-0204` | Bad Request | The extraction request is invalid. Please verify the parameters 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. |
## 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. |
**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. |
**409**
| `code` | `title` | `message` |
| ----------- | -------- | --------------------------------------------------------------------------------------------- |
| `MTCH-0305` | Conflict | The ingestion job is in an invalid state for this operation. Please verify its current state. |
## 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. |
**409**
| `code` | `title` | `message` |
| ----------- | -------- | --------------------------------------------------------------------------------------- |
| `MTCH-0408` | Conflict | A matching run is already in progress for this context. Please wait for it to complete. |
**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. |
## 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. |
**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. |
## 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. |
**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. |
## 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. |
**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. |