> ## 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 and idempotency contract

> Matcher documentation now describes the RFC 9457 error envelope and idempotency retry requirements.

<Badge stroke icon="calendar-days" iconType="regular">August 10, 2026</Badge> <Badge stroke icon="file-code" iconType="regular">Documentation correction</Badge> <Badge color="red" size="lg" stroke icon="triangle-exclamation" iconType="regular">Action required</Badge>

## Affects

***

Teams integrating with the **Matcher** API, especially clients that parse errors or retry requests with idempotency keys.

## What changed

***

The documentation now correctly states that Matcher errors use an RFC 9457 problem envelope with `title`, `status`, `detail`, and a stable `code`; field validation details use an `errors` array. It also documents the idempotency-key format (1–128 characters matching `^[A-Za-z0-9:_-]+$`) and the retry behavior for `MTCH-0015` and `MTCH-0018`.

This is a documentation correction; runtime behavior did not change.

## Impact

***

**Classification: Action required.** Clients that parse the former `message` or `details` fields, or generate idempotency keys without the documented constraints, must be aligned with the actual contract.

## What you need to do

***

<Steps>
  <Step>Update error handling to read `detail`, `status`, and field-level `errors` where applicable.</Step>
  <Step>Validate generated idempotency keys against the documented length and character constraints.</Step>
  <Step>Review retry handling for `MTCH-0015` and `MTCH-0018` before the next integration release.</Step>
</Steps>

### Deadline

No product-imposed deadline. Complete the review before your next Matcher client release.

## Resources

***

* [Matcher error list](/en/reference/matcher/matcher-error-list)
* [Retries and idempotency](/en/reference/retries-idempotency)