Referência de erros

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

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.