Matcher error list

Error format

{
   "type": "https://errors.lerian.studio/v1/<error_code>",
   "title": "<error_title>",
   "status": 400,
   "detail": "<error_detail>",
   "code": "<error_code>"
}

Field definitions

type – A URI that identifies the error, built as https://errors.lerian.studio/v1/<code>.
title – The HTTP status text (for example, Bad Request).
status – The HTTP status code.
detail – A short description of this occurrence of the error. Use code to branch programmatically.
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

When the request fails schema validation, Matcher returns 422 Unprocessable Entity with an errors array and no code. Examples:

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    { "message": "expected required property name to be present", "location": "body" }
  ]
}

{
  "type": "https://errors.lerian.studio/v1/MTCH-0005",
  "title": "Not Found",
  "status": 404,
  "detail": "No reconciliation context matches this id; check the context id and try again.",
  "code": "MTCH-0005"
}

General errors

These errors apply to all Matcher API endpoints. 400

`code`	`title`	Description
`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.

403

`code`	`title`	Description
`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`	Description
`MTCH-0005`	Not Found	The requested resource does not exist. Please verify the ID and try again.

409

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

413

`code`	`title`	Description
`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`	Description
`MTCH-0006`	Unprocessable Entity	The request was well-formed but could not be processed. Please verify the input data and try again.

500

`code`	`title`	Description
`MTCH-0002`	Internal Server Error	An unexpected error occurred. The `detail` is `internal error`.

503

`code`	`title`	Description
`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`	Description
`MTCH-0109`	Bad Request	A context name is required. Please provide a valid name and try again.

404

`code`	`title`	Description
`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`	Description
`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-0107`	Conflict	A resource with this priority already exists. Please choose a different priority value.
`MTCH-0108`	Conflict	The fee schedule is in use and cannot be deleted.
`MTCH-0118`	Conflict	The match rule cannot be deleted because a confirmed match group that it created still has an exception. Please change the rule’s 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`	Description
`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`	Description
`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`	Description
`MTCH-0205`	Conflict	A discovery refresh is already in progress. Please wait for it to complete before starting a new one.
`MTCH-0209`	Conflict	Matcher retired the connection, but it could not confirm the delete on the external system. Please check the external system for a connection that may still be live.

422

`code`	`title`	Description
`MTCH-0210`	Unprocessable Entity	Matcher cannot run connectivity tests for this aggregator vendor. No test ran and nothing changed.
`MTCH-0211`	Unprocessable Entity	The aggregator connection is not linked to an account yet. Matcher did not run the test. Please complete the hosted consent flow, then try again.
`MTCH-0212`	Unprocessable Entity	The aggregator vendor did not issue a consent token, and nothing changed. Please test the connection, then try again.
`MTCH-0213`	Unprocessable Entity	Matcher cannot open a hosted consent flow for this aggregator vendor, and nothing changed. Please contact support if you need the consent flow for this vendor.

503

`code`	`title`	Description
`MTCH-0203`	Service Unavailable	The extraction engine is temporarily unavailable. Please try again later.

Ingestion errors

Matcher returns these errors for transaction file upload and processing. 400

`code`	`title`	Description
`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`	Description
`MTCH-0319`	Forbidden	Document extraction is not enabled. Please contact support to opt in.

404

`code`	`title`	Description
`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`	Description
`MTCH-0311`	Request Timeout	The upload stalled because no data was received within the allowed time. Please retry the upload.

409

`code`	`title`	Description
`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`	Description
`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`	Description
`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`	Description
`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`	Description
`MTCH-0409`	Forbidden	Rule suggestion is not enabled. Please contact support to opt in.

409

`code`	`title`	Description
`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`	Description
`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`	Description
`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`	Description
`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	Matcher applied the resolution, but it could not confirm the updated exception record. Please reload the exception to see its current status.

409

`code`	`title`	Description
`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 exception. Please retry the request in a moment.
`MTCH-0511`	Conflict	The exception is already resolved, or a resolution is in progress. Please review its resolution details.

422

`code`	`title`	Description
`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`	Description
`MTCH-0506`	Too Many Requests	The callback rate limit has been exceeded. Please wait before retrying.

Governance errors

Audit log and governance operations return the general errors, such as MTCH-0005 when an audit log, actor mapping, or archive does not exist.

Reporting errors

Report export operations return the general errors. An export job that does not exist returns MTCH-0005, a job that is not ready for download or has already finished returns MTCH-0007, a disabled export worker returns MTCH-0702, and unavailable object storage returns MTCH-0019. An expired export file returns 410 with no code.

Rate limit errors

Matcher limits how many requests each caller can send in a time window. A request over the limit returns 429 before it reaches the operation, with a flat body in which code is the number 429. The Retry-After header gives the number of seconds to wait before you retry.

{
  "code": 429,
  "title": "rate_limit_exceeded",
  "message": "rate limit exceeded"
}

When Matcher cannot reach the store that counts requests, it rejects the request with 503 and a flat body of the same shape:

{
  "code": 503,
  "title": "service_unavailable",
  "message": "rate limiter temporarily unavailable"
}

Authentication errors

Access Manager checks the token and the caller’s permissions. A refusal from that check is not a problem object and carries no MTCH code. When Access Manager does not answer, Matcher answers 503. 401

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

403

`code`	`title`	Description
`MTCH-0004`	Forbidden	The token does not identify a tenant. Please verify your access level.

Idempotency errors

Matcher returns these errors for a problem with idempotency key handling. 400

`code`	`title`	Description
`MTCH-0015`	Bad Request	The idempotency key must contain 1 to 128 letters, digits, hyphens, underscores, or colons; no request was processed.

409

`code`	`title`	Description
`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.

500

`code`	`title`	Description
`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.

​Error format

​Field definitions

​Field-level error details

​General errors

​Configuration errors

​Discovery errors

​Ingestion errors

​Matching errors

​Exception errors

​Governance errors

​Reporting errors

​Rate limit errors

​Authentication errors

​Idempotency errors

Error format

Field definitions

Field-level error details

General errors

Configuration errors

Discovery errors

Ingestion errors

Matching errors

Exception errors

Governance errors

Reporting errors

Rate limit errors

Authentication errors

Idempotency errors