> ## 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.

# Contrato de erros e idempotência do Matcher

> A documentação do Matcher agora descreve o envelope de erros RFC 9457 e os requisitos de retentativa com idempotência.

<Badge stroke icon="calendar-days" iconType="regular">10 de agosto de 2026</Badge> <Badge stroke icon="file-code" iconType="regular">Correção de documentação</Badge> <Badge color="red" size="lg" stroke icon="triangle-exclamation" iconType="regular">Ação necessária</Badge>

## Afeta

***

Times que integram com a API do **Matcher**, especialmente clientes que fazem parse de erros ou tentam novamente requisições com chaves de idempotência.

## O que mudou

***

A documentação agora declara corretamente que os erros do Matcher usam um envelope de problema RFC 9457 com `title`, `status`, `detail` e um `code` estável; detalhes de validação por campo usam um array `errors`. Ela também documenta o formato da chave de idempotência (de 1 a 128 caracteres que correspondem a `^[A-Za-z0-9:_-]+$`) e o comportamento de retentativa para `MTCH-0015` e `MTCH-0018`.

Esta é uma correção de documentação; o comportamento de runtime não mudou.

## Impacto

***

**Classificação: Ação necessária.** Clientes que fazem parse dos campos anteriores `message` ou `details`, ou geram chaves sem essas restrições, devem se alinhar ao contrato real.

## O que você precisa fazer

***

<Steps>
  <Step>Atualize o tratamento de erros para ler `detail`, `status` e `errors` quando aplicável.</Step>
  <Step>Valide as chaves de idempotência geradas contra as restrições documentadas.</Step>
  <Step>Revise as retentativas de `MTCH-0015` e `MTCH-0018` antes da próxima versão da sua integração.</Step>
</Steps>

### Prazo

Não há prazo imposto pelo produto. Conclua a revisão antes da próxima versão do seu cliente Matcher.

## Recursos

***

* [Lista de erros do Matcher](/pt/reference/matcher/matcher-error-list)
* [Retentativas e idempotência](/pt/reference/retries-idempotency)