# Referência de erros

Códigos estáveis para decidir renovação, correção de entrada, conflito, compatibilidade e retry.

[Abrir a versão HTML](https://rhizzalab.com/docs/reference/errors)

## Use o código para controle de fluxo

Mensagens são próprias para exibição em português, mas podem evoluir em clareza. Para lógica de recuperação, compare `error.code` com a taxonomia fechada.

```tsx
function handleEditorError(error: { code: string; message: string }) {
  switch (error.code) {
    case "AUTH_REQUIRED":
      return renewEditorToken()
    case "CONFLICT":
      return openConflictResolution()
    case "RATE_LIMITED":
      return showRetryLater()
    default:
      return showEditorError(error.message)
  }
}
```

## Taxonomia do editor

| Código                   | HTTP sugerido | O que fazer                                            |
| ------------------------ | ------------- | ------------------------------------------------------ |
| `AUTH_REQUIRED`          | 401           | Obter outro token pelo backend do host                 |
| `FORBIDDEN_REPORT`       | 403           | Remover o acesso àquele `reportType` e revisar o grant |
| `INVALID_DATA`           | 422           | Corrigir `data` usando os paths de `issues`            |
| `INVALID_CONFIG`         | 422           | Corrigir configuração de bloco ou cadastro             |
| `INVALID_DOCUMENT`       | 422           | Interromper a abertura e investigar a árvore           |
| `PROTOCOL_INCOMPATIBLE`  | 426           | Alinhar versões do protocolo e do SDK                  |
| `PRIMITIVES_UNSUPPORTED` | 426           | Atualizar o SDK para as primitivas exigidas            |
| `CONFLICT`               | 409           | Pedir resolução explícita; não sobrescrever            |
| `RATE_LIMITED`           | 429           | Aguardar e repetir de forma limitada                   |
| `INTERNAL`               | 500           | Oferecer retry e registrar o request id                |

## Mostre problemas por caminho

Erros de validação podem trazer `issues` com caminhos JSON Pointer. Use-os para localizar a origem no payload e, quando fizer sentido, destacar o campo correspondente no seu produto.

```json
{
  "code": "INVALID_DATA",
  "message": "Os dados enviados não correspondem ao schema do relatório.",
  "issues": [
    {
      "path": "/items/2/quantity",
      "message": "deve ser maior que zero"
    }
  ],
  "requestId": "req_..."
}
```

## Repita somente o que pode se recuperar

* Renove uma vez após `AUTH_REQUIRED`; se a sessão do host acabou, volte ao login.

* Use backoff para `RATE_LIMITED` e falhas de rede.

* Não repita `INVALID_DATA`, incompatibilidade ou acesso proibido sem mudar a entrada.

* Preserve `requestId`, código e etapa da operação; nunca registre token, secret ou conteúdo do documento.