# O que fazer quando dá errado

O erro aparece perto da causa, diz o que fazer, e nunca apaga o que a pessoa
digitou.

## O problema

Erro que devolve o formulário vazio custa o trabalho inteiro de novo, e é o
motivo mais comum de abandono. Erro que só diz "Algo deu errado" deixa a pessoa
sem saber se espera, corrige ou liga para alguém. E a tela que desenha só o
caminho feliz entrega metade, e a metade que falta é a que aparece no pior dia.

## Quando usar

Em toda ação que pode falhar e em toda consulta. Toda consulta tem quatro
finais, e cada um é uma decisão de fluxo, não só uma tela:

| Final | A decisão |
|---|---|
| carregando | esqueleto na forma do conteúdo que vem ([espera.md](https://ds.rivocode.com.br/padroes/espera.md)) |
| erro | o que a pessoa faz agora, e se repetir resolve |
| vazio | é a primeira vez dela, ou o filtro não achou? São textos e ações diferentes |
| dados | o caminho feliz |

## Quando não usar

- **`Toast` não serve para erro que exige ação.** Ele some. O que precisa
  continuar visível é `Alert`.
- **Página de erro inteira não serve para o pedaço que falhou.** Se o resto da
  tela funciona, o erro fica no lugar do pedaço: [experiencia-degradada.md](https://ds.rivocode.com.br/padroes/experiencia-degradada.md).
- **Vazio não é erro.** Dado que não veio porque a consulta falhou não vira
  "Nenhum resultado".

## As peças

- `FieldError` e o `FormField`: o erro de campo, no campo.
- `FormErrorSummary`: os erros do envio, no topo do formulário, com link para
  cada campo.
- `Alert`: o erro da operação, que fica na tela.
- `QueryBoundary`, `DataTable` e as peças de consulta com `isError`,
  `errorTitle`, `errorMessage` e `onRetry`: o erro de carga no lugar do
  conteúdo. Quando ele toma a página ou a seção, `errorIllustration` leva o
  desenho (`ServerError`, ou o Bacalhau triste em produto da RivoCode) e troca
  o aviso pelo `Result` de perigo.
- `Result` com `tone="danger"` e `illustration`: o fim de fluxo que falhou, e
  a página de erro (404, 403, 500, sem conexão).

## Comportamento

- **Preserve o que a pessoa digitou.** O que foi digitado continua nos campos,
  sempre. O `reset` mora no caminho do sucesso, e nunca no `catch` nem no
  `onError`.
- **O erro aparece perto da causa.** Erro de campo no campo; erro da operação no
  topo do formulário ou num `Alert`; erro de carregamento no lugar do conteúdo
  que não veio.
- **Erro que se resolve repetindo ganha `onRetry`.** O que não se resolve
  repetindo ganha o caminho: quem procurar, ou o que corrigir.
- **Valide na saída do campo, não a cada tecla.** Cobrar o CNPJ completo no
  terceiro dígito é acusar quem ainda está digitando. Depois do primeiro erro,
  o campo revalida a cada tecla, para o erro sumir assim que for corrigido.
- **O botão de enviar não espera o formulário ficar válido.** Desabilitado, ele
  não diz o que falta; habilitado, o clique mostra.
- **O vazio de filtro devolve o filtro**, e não oferece "criar": quem filtrou
  quer o filtro de volta.

```tsx
<QueryBoundary
  data={invoices.data}
  isLoading={invoices.isPending}
  isError={invoices.isError}
  onRetry={invoices.refetch}
  errorTitle="Não foi possível carregar as notas"
  errorMessage="A prefeitura não respondeu. Tente de novo em alguns minutos."
  skeleton={<InvoiceListSkeleton />}
>
  {(list) => <InvoiceList invoices={list} />}
</QueryBoundary>
```

## Texto

Duas frases, cada uma com um trabalho:

- **O título diz o que falhou**, nomeando o objeto: "Não foi possível carregar
  as notas". Nunca "Erro" nem "Algo deu errado".
- **A descrição diz quem falhou e o que fazer**: "A prefeitura não respondeu.
  Tente de novo em alguns minutos."
- **Erro de campo diz o formato aceito**: "Use o formato 00.000.000/0000-00", e
  não "Valor inválido".
- Nunca código de erro, `stack` ou nome de endpoint na tela. O que se oferece
  para copiar é o código do atendimento, que o suporte procura no log.

As formas completas estão em [texto.md](https://ds.rivocode.com.br/skill/reference/texto.md).

## Acessibilidade

- O erro de campo se liga ao campo por `aria-describedby`, e o campo ganha
  `aria-invalid`: o `FormField` já faz.
- No envio que falha, o foco vai ao `FormErrorSummary` ou ao primeiro campo com
  erro, e não fica parado no botão.
- O `Alert` de `danger` e `warning` sai com `role="alert"`; o erro de carga do
  `QueryBoundary` é anunciado no lugar dele.
- Cor nunca é o único sinal: o erro tem ícone e texto.

## No celular e no nativo

No celular o erro de campo pode ficar embaixo do teclado: o foco no primeiro
campo com erro rola até ele. O `QueryBoundary`, o `Alert`, o `Result` e o
`DataList` do `@rivocode/ui-native` falam os mesmos nomes (`isError`,
`errorTitle`, `errorMessage`, `onRetry`), com o texto em `string`. O formulário
nativo entra por outro caminho: [native.md](https://ds.rivocode.com.br/skill/reference/native.md).

## Os blocos que o aplicam

- [Login](https://ds.rivocode.com.br/blocos#login)
- [Cadastro de paciente](https://ds.rivocode.com.br/blocos#cadastro)
- [Vazio, erro e carregando](https://ds.rivocode.com.br/blocos#vazio-e-erro)
- [Modelo do e-mail de boas-vindas](https://ds.rivocode.com.br/blocos#modelo-de-e-mail)
- [Fechamento do caixa](https://ds.rivocode.com.br/blocos#fechamento-do-caixa)
- [Página não encontrada (404)](https://ds.rivocode.com.br/blocos#pagina-nao-encontrada)
- [Erro inesperado (500)](https://ds.rivocode.com.br/blocos#erro-inesperado)
