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

# Lista de erros do Reporter

> O Reporter retorna respostas de erro consistentes e estruturadas. Consulte os códigos de erro, os status HTTP e as etapas de correção para resolver falhas de API rapidamente.

**Formato do erro**

O Reporter retorna erros como problem details RFC 9457 com o tipo de mídia `application/problem+json`:

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/RPT-0012",
  "title": "Bad Request",
  "status": 400,
  "detail": "The specified templateID is not a valid UUID. Please check the value passed.",
  "code": "RPT-0012"
}
```

**Definições de campos**

* **`type`** – Uma URI que identifica o erro no catálogo de erros da Lerian. Construída como `https://errors.lerian.studio/v1/<code>`.
* **`title`** – O texto do status HTTP (por exemplo, `Bad Request`).
* **`status`** – O código de status HTTP.
* **`detail`** – Orientação detalhada para ajudar você a resolver o erro. Para respostas `5xx`, o Reporter sempre higieniza o detail para `internal error`, para que nenhuma causa interna vaze. Use `code` para tratar o erro de forma programática.
* **`code`** – Um identificador estável e único para o erro (`RPT-NNNN`). Útil para tratamento programático e solicitações de suporte.
* **`errors`** – Lista opcional de detalhes de validação por campo, cada um com uma `message` e uma `location`.

Algumas mensagens contêm placeholders como `%v` ou `%s`. O Reporter os substitui pelos valores específicos da sua requisição.

## Erros do Reporter

***

As tabelas abaixo listam os erros que podem ocorrer quando você chama os endpoints do Reporter, o que cada um significa e como resolvê-lo.

## 400: Erros de validação

***

| `code` | Descrição | `detail` |
| - | - | :- |
| RPT-0001 | Campos obrigatórios ausentes | Um ou mais campos obrigatórios estão ausentes. Confirme que todos os campos obrigatórios foram incluídos. |
| RPT-0002 | Formato de arquivo inválido | O arquivo enviado deve ser um arquivo .tpl. Outros formatos não são aceitos. |
| RPT-0003 | Formato de saída inválido | O campo outputFormat deve ser um dos seguintes: html, csv, pdf, txt ou xml. |
| RPT-0004 | Header inválido | Um ou mais valores de header estão ausentes ou formatados incorretamente. Verifique os headers obrigatórios %v. |
| RPT-0005 | Arquivo enviado inválido | O arquivo enviado é inválido. Verifique o arquivo enviado com o erro: %v |
| RPT-0006 | Erro de arquivo vazio | O arquivo enviado está vazio. Verifique o arquivo enviado. |
| RPT-0007 | Erro de conteúdo de arquivo inválido | O conteúdo do arquivo é inválido porque não é %s. Verifique o arquivo enviado. |
| RPT-0008 | Campos de mapeamento inválidos | O campo no arquivo de template é inválido. Campo inválido %s em %s. |
| RPT-0009 | Parâmetro de caminho inválido | Os parâmetros de caminho estão em um formato incorreto. Verifique o seguinte parâmetro %v e garanta que atendam ao formato exigido antes de tentar novamente. |
| RPT-0010 | Atualização de formato de saída sem arquivo de template | Não é possível atualizar o formato de saída sem enviar um arquivo de template. Verifique as informações enviadas e tente novamente. |
| RPT-0012 | templateID inválido | O templateID especificado não é um UUID válido. Verifique o valor informado. |
| RPT-0013 | ledgerID inválido | O ledgerID especificado dentro da lista de ledger ID não é um UUID válido. Verifique o valor informado %v. |
| RPT-0014 | Campos obrigatórios ausentes | Os campos mapeados no arquivo de template estão ausentes no esquema da tabela ou podem estar vazios. Verifique os campos informados: '%v'. |
| RPT-0015 | Campos inesperados na requisição | O corpo da requisição contém mais campos do que o esperado. Envie apenas os campos permitidos conforme a documentação. Os campos inesperados estão listados no objeto fields. |
| RPT-0016 | Campos ausentes na requisição | Sua requisição está sem um ou mais campos obrigatórios. Consulte a documentação para garantir que todos os campos necessários estejam incluídos na sua requisição. |
| RPT-0017 | Requisição inválida | O servidor não conseguiu entender a requisição devido a sintaxe malformada. Verifique os campos listados e tente novamente. |
| RPT-0019 | Parâmetro de consulta inválido | Um ou mais parâmetros de consulta estão em um formato incorreto. Verifique os seguintes parâmetros '%v' e garanta que atendam ao formato exigido antes de tentar novamente. |
| RPT-0023 | Erro de intervalo de datas inválido | Os campos 'initialDate' e 'finalDate' são obrigatórios e devem estar no formato 'yyyy-mm-dd'. Informe datas válidas e tente novamente. |
| RPT-0024 | Limite de paginação excedido | O limite de paginação excede o máximo permitido de %v itens por página. Verifique o limite e tente novamente. |
| RPT-0025 | Ordem de classificação inválida | O campo 'sort\_order' deve ser 'asc' ou 'desc'. Informe uma ordem de classificação válida e tente novamente. |
| RPT-0026 | Tamanho da chave de metadados excedido | A chave de metadados %v excede o tamanho máximo permitido de %v caracteres. Use uma chave mais curta. |
| RPT-0027 | Tamanho do valor de metadados excedido | O valor de metadados %v excede o tamanho máximo permitido de %v caracteres. Use um valor mais curto. |
| RPT-0028 | Aninhamento de metadados inválido | O objeto de metadados não pode conter valores aninhados. Garanta que o valor %v não esteja aninhado e tente novamente. |
| RPT-0030 | Tabela de esquema ausente | A tabela de esquema %v está ausente para a fonte de dados '%v'. Verifique as informações informadas. |
| RPT-0031 | Tabela de fonte de dados ausente | A fonte de dados %v está ausente. Verifique o valor informado. |
| RPT-0032 | Tag de script detectada | O arquivo de template contém uma tag de script, o que não é permitido. Verifique o arquivo de template e tente novamente. |
| RPT-0035 | Referência de esquema ambígua | A tabela '%v' existe em vários esquemas: %v. Qualifique-a com o esquema dela, como schema\_\_%v. |
| RPT-0036 | Esquema não encontrado | O esquema '%v' não foi encontrado no banco de dados '%v'. Verifique o nome do esquema. |
| RPT-0037 | Tabela não encontrada no esquema | A tabela '%v' não foi encontrada no esquema '%v' do banco de dados '%v'. Verifique o nome da tabela e do esquema. |
| RPT-0038 | Banco de dados não registrado | O banco de dados '%v' não está registrado. Verifique a configuração da fonte de dados. |
| RPT-0041 | Bucket obrigatório | O nome do bucket de armazenamento é obrigatório. Verifique a configuração de armazenamento. |
| RPT-0042 | Chave do objeto obrigatória | A chave do objeto é obrigatória para a operação de armazenamento. |
| RPT-0044 | TTL não aceito | O parâmetro TTL não é aceito no modo S3. Use políticas de ciclo de vida do bucket. |
| RPT-0046 | Tipo de prazo inválido | O campo 'type' deve ser 'regulatory' ou 'custom'. Informe um tipo de prazo válido e tente novamente. |
| RPT-0047 | Frequência de prazo inválida | O campo 'frequency' deve ser um dos seguintes: 'once', 'daily', 'weekly', 'monthly', 'semiannual', 'annual'. Informe uma frequência válida e tente novamente. |
| RPT-0048 | Cor de prazo inválida | O campo 'color' deve ser um código de cor hexadecimal válido (por exemplo, '#FF5733'). Informe uma cor válida e tente novamente. |
| RPT-0050 | Meses do ano não aplicável | O campo 'monthsOfYear' não é aplicável para a frequência '%v'. Ele apenas pode ser usado com as frequências 'semiannual' ou 'annual'. |
| RPT-0052 | Meses do ano obrigatório | O campo 'monthsOfYear' é obrigatório para a frequência '%v'. Especifique em quais meses do ano o prazo deve recorrer. |
| RPT-0054 | Meses do ano fora do intervalo | Cada valor em 'monthsOfYear' deve estar entre 1 e 12. Valor inválido recebido: %v. |
| RPT-0055 | Data de vencimento no passado | O campo 'dueDate' deve ser hoje ou uma data futura. Informe uma data que não esteja no passado. |
| RPT-0056 | Divergência na contagem de meses do ano | O número de meses em 'monthsOfYear' não corresponde à frequência '%v'. 'semiannual' exige exatamente 2 meses e 'annual' exige exatamente 1 mês. |
| RPT-0059 | Falha na validação de esquema | A validação de esquema falhou. Verifique os campos em relação ao esquema da fonte de dados. |
| RPT-0062 | Codificação UTF-8 inválida | O campo '%v' contém sequências de bytes UTF-8 inválidas. Informe um texto UTF-8 válido e tente novamente. |
| RPT-0073 | Nome de configuração reservado da fonte de dados | O `configName` é reservado para uma fonte de dados gerenciada pelo operador e não pode ser atribuído ou renomeado pela API. |
| RPT-0075 | Escopo de organização do CRM não resolvido | O escopo de organização da fonte de dados de CRM não pôde ser resolvido, então o template não pode ser salvo com segurança. |
| RPT-0076 | Tabela de filtro não extraída | A tabela de filtro não corresponde a nenhuma tabela mapeada pelo template do relatório. Use uma das tabelas mapeadas. |
| RPT-0077 | Valor de filtro não pode ser lido como data | O valor do filtro não pode ser lido como uma data para o campo. Use um valor de data ou hora ISO apropriado para esse campo. |
| RPT-0078 | Arquivo de template muito grande | O arquivo de template excede o limite de bytes aceito. Divida o relatório em templates menores e tente novamente. |
| RPT-0079 | Conflito de operadores de filtro | O filtro combina operadores que não podem ser usados juntos. Mantenha um operador compatível para o campo. |
| RPT-0080 | Campo de fonte de dados inválido | Um campo da fonte de dados é inválido. Corrija o campo identificado e envie a requisição novamente. |
| RPT-0090 | Template mapeia colunas demais | O template mapeia mais colunas do que um relatório pode processar. Reduza as colunas mapeadas ou divida o template. |
| RPT-0095 | Limite de filtro sem valor | Um operador de filtro não tem um valor comparável. Informe um valor ou remova o operador. |
| RPT-0096 | Filtro custa mais do que uma consulta pode suportar | Os filtros excedem um limite de recursos da consulta. Reduza os valores do filtro ou restrinja a requisição. |
| RPT-0097 | Operador de filtro traz o número errado de valores | O operador de filtro recebeu um número incorreto de valores. Por exemplo, `between` exige exatamente dois valores. |
| RPT-0105 | Valor de filtro não pode ser lido em relação ao campo que filtra | O valor do filtro não pode ser lido como o tipo mantido pelo campo. Use um valor compatível ou um campo compatível com data. |
| RPT-0106 | Cursor inválido | O cursor não foi emitido por esta API ou não identifica mais uma posição usável. Reinicie a listagem e siga o `nextCursor`. |
| RPT-0107 | Falha na pré-visualização do template | A pré-visualização do template não pôde ser renderizada. Corrija o template ou os dados de amostra e tente novamente. O detail da resposta identifica a recusa específica. |
| RPT-0110 | Período do filtro não pode dividir o campo | O campo do filtro usa `period` junto com outro operador. Um período já define as duas pontas do intervalo. Mantenha só o período, ou remova-o e informe as duas datas. |
| RPT-0111 | Filtro do lembrete maior do que um lembrete comporta | O filtro completo do prazo excede o que um prazo consegue armazenar. Divida-o em mais de um prazo, cada um com menos tabelas. |
| RPT-0112 | Filtro nomeia algo que não pode ser um nome | Uma chave de filtro não consegue nomear uma fonte de dados, uma tabela ou um campo. Corrija a chave. Se uma automação a preencheu, verifique a variável que a alimenta. |
| RPT-0120 | Categoria do template obrigatória | O template não tem categoria. Envie `category` com a família em que o relatório é arquivado, como `cadoc`. |
| RPT-0121 | Categoria do template não é um nome de família usável | A categoria deve corresponder a `^[a-z0-9_-]{1,100}$`. O Reporter corrige maiúsculas e espaços nas pontas, mas recusa espaço interno, ponto, barra ou acento. |
| RPT-0122 | Template sem categoria | O prazo nomeia um template sem categoria. Arquive o template em uma categoria e envie o prazo de novo, sem alterações. |
| RPT-0123 | Templates demais em uma associação de categoria | A requisição associa uma categoria a mais templates do que uma requisição comporta. Divida o trabalho em lotes menores. |
| RPT-0124 | Associação de categoria sem template | A requisição não nomeia nenhum template. Envie `templateIds` com pelo menos um ID de template. |
| RPT-0130 | Fuso horário do prazo inválido | O campo `timezone` deve ser um nome de fuso horário IANA válido, como `America/Sao_Paulo`. |
| RPT-0131 | Período do filtro não é uma janela conhecida | O valor de `period` não é uma janela que o Reporter conhece. Escreva uma das janelas listadas no detail, exatamente como aparece. |
| RPT-0134 | Condição de filtro sem operador | Um campo do filtro não nomeia operador, então não restringiria o relatório. Informe um operador com seus valores, ou remova o campo do filtro. |
| RPT-0135 | Fonte de dados usa um nome reservado | O nome `system` é reservado para os parâmetros de geração do relatório. Escolha outro `configName`. |
| RPT-0137 | Contrato de documento inválido | O contrato do documento regulatório não pode ser carregado. O detail indica o ponto a corrigir. |
| RPT-0138 | Valor recusado pelo contrato do documento | Um valor produzido para um campo não é permitido pelo contrato do documento. Corrija o binding ou os dados por trás dele e gere o relatório de novo. |
| RPT-0139 | Documento regulatório fora deste catálogo | O template se refere a um documento regulatório que este deploy não oferece. Informe um documento do catálogo. |
| RPT-0140 | Parâmetro de geração ausente ou inválido | Um parâmetro de geração que o template declara está ausente ou inválido, ou o template declara um parâmetro malformado. Corrija os `parameters` da requisição ou a declaração. |
| RPT-0141 | Template marca uma posição que o contrato não declara | O template marca um campo que o contrato do documento regulatório não declara. Corrija o nome no template. |
| RPT-0142 | Template regulatório não é enviado | Um documento regulatório curado recebe o layout do catálogo, então nenhum arquivo de template é enviado para ele. Informe o documento e a fonte de dados dele, ou crie um relatório personalizado. |
| RPT-0143 | Binding do documento inválido | O binding do documento não pode ser lido. O detail indica o ponto a corrigir. Corrija-o e salve o binding de novo. |
| RPT-0146 | Subscription inválida | A subscription não pode ser usada como está. O detail indica o que corrigir. |
| RPT-0149 | A correção não pode ser aplicada | A correção não é válida para a posição dela no documento. Corrija-a na posição indicada e aplique de novo. |
| RPT-0153 | A proveniência do relatório está incompleta | O registro de proveniência congelado do relatório não tem um elemento obrigatório, então o Reporter se recusou a gravá-lo. O detail indica o elemento. |
| RPT-0154 | O conteúdo do catálogo não é o que foi publicado | A release do catálogo falhou na verificação de integridade e foi recusada. O catálogo em vigor não muda. Verifique a release e o caminho por onde ela chegou. |
| RPT-0155 | Não é possível buscar a release regulatória | A origem do catálogo não conseguiu fornecer os arquivos do documento, então nada foi gravado. Tente de novo quando a origem responder. Documentos que já têm subscription não são afetados. |
| RPT-0165 | Template com macro recursiva | Uma macro do template chama a si mesma, diretamente ou por outra macro, então a renderização nunca terminaria. Quebre o ciclo e envie o template de novo. |
| RPT-0166 | Template formata um valor e depois o altera | O template aplica outro filtro depois do filtro `decimal`, o que colocaria um valor errado no arquivo. Mova o outro filtro para antes de `decimal`, ou remova-o. |
| RPT-0169 | A instituição é inválida | Um campo da instituição é inválido: um nome em branco, um CNPJ cujos dígitos verificadores não conferem ou um escopo malformado. Corrija o campo e envie a instituição de novo. |
| RPT-0173 | Nenhuma tabela de organização do Midaz | Nenhuma das fontes de dados informadas tem a tabela de organização do Midaz, então não há organização para propor como instituição. Informe a fonte de dados do banco de onboarding do Midaz. |
| RPT-0174 | A fonte de dados não é PostgreSQL | O Reporter só propõe instituições a partir de bancos PostgreSQL do Midaz. Omita a fonte de dados, ou informe a fonte de dados do banco de onboarding do Midaz. |
| RPT-0175 | Mais de uma tabela de organização do Midaz | As fontes de dados informadas têm mais de uma tabela de organização do Midaz. Informe apenas a fonte de dados do banco de onboarding do Midaz. |
| RPT-0180 | Escolha a instituição | O tenant tem várias instituições e a requisição não nomeia nenhuma. Defina `institution` com um ID de instituição, ou com `all` para ler as linhas de todas as instituições em um único relatório. |
| RPT-0181 | A instituição não cobre esta tabela | O relatório lê uma tabela que o escopo da instituição não filtra nem marca como compartilhada. Adicione a tabela ao escopo da instituição e solicite o relatório de novo. |
| RPT-0183 | A seleção de instituição é inválida | O valor de `institution` não é um ID de instituição nem `all`, ou é `all` em uma remessa regulatória, que declara exatamente uma instituição. |
| RPT-0190 | Escolha a instituição que faz a remessa | Uma remessa regulatória declara exatamente uma instituição. A requisição não nomeia nenhuma, e o tenant não tem exatamente uma. Informe a instituição que faz a remessa, também na subscription quando ela for anterior às instituições, e cadastre uma primeiro se o tenant não tiver nenhuma. |
| RPT-0193 | O filtro de prefixo precisa de texto | Um filtro `startsWith` ou `notStartsWith` traz uma entrada que não é um texto não vazio, ou aponta para uma coluna que não guarda texto. Dê a cada entrada um prefixo de texto não vazio, em uma coluna de texto. |
| RPT-0196 | O declarante não é a instituição | O CNPJ que a remessa declara não é o CNPJ da instituição para a qual a remessa é gerada. A geração termina em `Error`, e uma correção com esse valor é recusada. Corrija o CNPJ onde o mapeamento o lê, ou o cadastro da instituição. |

### RPT-0075: Escopo de organização do CRM não resolvido

`RPT-0075` é uma proteção fail-closed para templates que mapeiam `plugin_crm`. O Reporter não salva nem executa um mapeamento de CRM sem escopo, porque isso poderia expor registros entre organizações do Midaz. Pode ocorrer ao importar, criar ou atualizar um template de CRM, e quando um worker resolve um template de CRM já salvo.

Não trate esse código como prova de que falta uma única variável de ambiente. Ele também ocorre quando o Reporter não consegue localizar `plugin_crm` no registro de fontes de dados. Primeiro confirme que o template mapeia `plugin_crm`, depois verifique a configuração do Manager e do worker, a disponibilidade do registro e as configurações não sensíveis de conexão do CRM.

Para um deploy self-hosted, configure o bloco completo `DATASOURCE_CRM_*`, incluindo `DATASOURCE_CRM_MIDAZ_ORGANIZATION_ID`, e mantenha a senha do CRM e `CRYPTO_HASH_SECRET_KEY_CRM` / `CRYPTO_ENCRYPT_SECRET_KEY_CRM` em Secrets. Essas chaves de criptografia devem ser as mesmas usadas pelo CRM, e `DATASOURCE_CRED_ENC_KEY` deve permanecer estável. Na inicialização do Manager, o seed reservado da fonte de dados pode preencher um `metadata.midazOrganizationId` ausente ou vazio. O seed nunca sobrescreve um valor persistido não vazio.

Não crie nem faça PATCH em `plugin_crm` pela API comum de fontes de dados. Se um ID de organização persistido e não vazio estiver incorreto, interrompa a recuperação genérica e fale com o suporte da Lerian. Após uma alteração aprovada, importe ou salve o template, gere um relatório, confirme que os campos de CRM são descriptografados e verifique o isolamento de organização. Veja [Reporter via Helm](https://github.com/LerianStudio/helm/tree/main/charts/reporter) para os valores do chart.

## 401: Não autorizado

***

| `code` | Descrição | `detail` |
| - | - | - |
| RPT-0158 | Autor da ação não identificado | A requisição foi autorizada, mas não identifica quem está agindo, e o Reporter registra cada correção e aprovação em nome de uma pessoa. Apresente um token que carregue uma claim de subject. |

## 404: Não encontrado

***

| `code` | Descrição | `detail` |
| - | - | :- |
| RPT-0011 | Entidade não encontrada | Nenhuma entidade %v foi encontrada para o ID informado. Use o ID correto da entidade que você está tentando gerenciar. |
| RPT-0020 | Erro de formato de data inválido | 'initialDate', 'finalDate', ou ambos, estão em formato incorreto. Use o formato 'yyyy-mm-dd' e tente novamente. |
| RPT-0021 | Erro de data final inválida | 'finalDate' não pode ser anterior a 'initialDate'. Verifique as datas e tente novamente. |
| RPT-0022 | Erro de intervalo de datas excede o limite | O intervalo entre 'initialDate' e 'finalDate' excede o limite permitido de %v meses. Ajuste as datas e tente novamente. |
| RPT-0043 | Objeto não encontrado | O objeto solicitado não foi encontrado no armazenamento. |
| RPT-0057 | Fonte de dados não encontrada | A fonte de dados solicitada não foi encontrada. Verifique o ID da fonte de dados. |
| RPT-0147 | Documento regulatório indisponível | O documento regulatório não está no catálogo deste deploy, ou o deploy não tem catálogo. Liste o catálogo para ver quais documentos ele oferece. |

## 409: Conflitos

***

| `code` | Descrição | `detail` |
| - | - | :- |
| RPT-0039 | Requisição duplicada em andamento | Uma requisição duplicada está sendo processada no momento. Aguarde e tente novamente. |
| RPT-0040 | Conflito de idempotência | Uma requisição com esta chave de idempotência já foi processada. |
| RPT-0045 | Prazo duplicado | Já existe um prazo com o mesmo nome, tipo, data de vencimento e frequência. Use valores diferentes ou atualize o prazo existente. |
| RPT-0071 | Conflito de nome de configuração da fonte de dados | Já existe uma fonte de dados com o mesmo `configName`. Use um `configName` diferente e tente novamente. |
| RPT-0072 | Fonte de dados em uso por template | A fonte de dados é referenciada por templates e não pode ser excluída ou renomeada. Atualize ou remova esses templates primeiro. |
| RPT-0144 | O binding mudou enquanto você editava | Alguém salvou o binding depois que você o abriu. Recarregue o binding, aplique sua alteração sobre ele e salve de novo. |
| RPT-0145 | O documento já tem subscription | A instituição já entrega este documento por outra subscription. Edite o binding dessa subscription, ou cancele-a primeiro. |
| RPT-0150 | O rascunho mudou enquanto você editava | Alguém corrigiu o rascunho depois que você o abriu. Recarregue o rascunho, aplique sua correção sobre ele e tente de novo. |
| RPT-0151 | O relatório já foi aprovado | Um relatório aprovado não muda. Para entregar algo diferente, gere um novo relatório. |
| RPT-0152 | O relatório não é um rascunho | Uma correção só se aplica a um rascunho. O relatório ainda está sendo gerado, ou a geração dele falhou. |
| RPT-0156 | Rascunho com campos obrigatórios em branco | Campos obrigatórios do rascunho estão sem valor. Preencha cada um com uma correção e depois aprove ou baixe o rascunho. |
| RPT-0167 | Outra subscription do documento está ativa | Outra subscription já entrega este documento para a mesma instituição. Desative essa subscription primeiro, ou mantenha esta inativa. |
| RPT-0168 | Fonte de dados nativa | A plataforma fornece esta fonte de dados e ela é somente leitura. Não é possível atualizá-la, excluí-la ou testá-la, nem registrar outra fonte de dados com o nome dela. |
| RPT-0170 | O CNPJ já está cadastrado | O tenant já cadastrou uma instituição com este CNPJ. Edite essa instituição, ou exclua-a primeiro. |
| RPT-0171 | A instituição mudou enquanto você editava | Alguém atualizou a instituição depois que você a leu. Leia-a de novo, aplique sua alteração sobre ela e salve com o ETag que ela retornar. |
| RPT-0182 | A instituição está em uso | Prazos ou subscriptions regulatórias ativas ainda geram relatórios para esta instituição. Aponte os prazos para outra instituição ou exclua-os, desative as subscriptions e exclua a instituição de novo. |
| RPT-0191 | A subscription mudou enquanto você editava | Alguém alterou a subscription depois que você a leu. Leia-a de novo e grave com a versão que ela retornar. |
| RPT-0197 | O período já tem um original aprovado | O período já tem uma remessa original aprovada, então o Reporter recusa outro original, na geração e na aprovação. Para remeter o período de novo, gere uma substituição. |
| RPT-0198 | Ainda não há o que substituir | O período não tem uma remessa original aprovada, então uma substituição não tem o que substituir. Gere o original e aprove-o primeiro. |
| RPT-0199 | Outra versão está publicada agora | A subscription ou a adoção nomeia uma versão diferente da que o catálogo publica agora. Leia a versão que o catálogo publica e envie a requisição de novo. |

## 412: Falha de pré-condição

***

| `code` | Descrição | `detail` |
| - | - | - |
| RPT-0074 | Proteção de credencial da fonte de dados não configurada | A proteção de credencial não está configurada. Defina `DATASOURCE_CRED_ENC_KEY` e tente novamente. |

## 422: Não processável

***

| `code` | Descrição | `detail` |
| - | - | :- |
| RPT-0029 | Status do relatório não é Finished | O relatório não está pronto para download. O relatório ainda está em processamento. |
| RPT-0157 | Artefato armazenado não corresponde à proveniência | O checksum do arquivo armazenado não corresponde ao checksum congelado quando o relatório foi renderizado, então o Reporter não entrega o arquivo. Gere o relatório de novo, ou investigue o armazenamento. |

## 428: Pré-condição obrigatória

***

| `code` | Descrição | `detail` |
| - | - | - |
| RPT-0148 | Versão do binding obrigatória | Salvar um binding exige o header `If-Match` com o ETag da última leitura. Leia o binding de novo e salve com esse ETag. |
| RPT-0172 | Versão da instituição obrigatória | Atualizar uma instituição exige o header `If-Match` com o ETag da última leitura. Leia a instituição de novo e salve com esse ETag. |
| RPT-0192 | Versão da subscription obrigatória | Alterar uma subscription exige o header `If-Match` com a versão da última leitura. Leia a subscription de novo e grave com essa versão. |

## 429: Muitas requisições

***

| `code` | Descrição | `detail` |
| - | - | :- |
| RPT-0108 | Pré-visualização de template ocupada | Todos os slots configurados de pré-visualização simultânea estão em uso, para uma pré-visualização de template ou de consulta do mapeamento. Nada foi rejeitado; tente a pré-visualização novamente em breve. |

## 500: Erros do servidor

***

| `code` | Descrição | `detail` |
| - | - | :- |
| RPT-0018 | Erro interno do servidor | internal error |
| RPT-0034 | Erro de comunicação com o SeaweedFS | internal error |

> [!NOTE]
>
> Toda falha inesperada durante o tratamento síncrono de endpoints surge como HTTP 500. A resposta carrega `code: RPT-0018`, ou `code: RPT-0034` quando o armazenamento de arquivos falha, e um detail higienizado `internal error`. Causas internas nunca vazam para o corpo da resposta. Falhas assíncronas de worker e de geração de relatório seguem, em vez disso, os status e metadados de relatório descritos abaixo. O Reporter não as retorna para a requisição original como HTTP 500.

## Erros de geração de relatório (assíncronos)

***

A geração de relatório é executada de forma assíncrona no worker. A requisição HTTP original nunca recebe uma seção de extração de dados com falha. O relatório termina com status `Error` quando todas as seções falham, ou `Partial` quando algumas falham.

Em ambos os casos, `metadata.error_code` é `RPT-0060`. As chaves de `metadata.sections` são nomes de bancos de dados. Cada entrada com falha contém seu `error_code` classificado (`RPT-0018` para uma falha não tipada). Uma entrada `RPT-0075` também carrega uma mensagem `remediation`.

Quando o worker encerra um relatório com uma recusa RPT, o relatório fica com status `Error`. `metadata.error_code` traz o código RPT, `metadata.error_title` o título dele, e `metadata.error` a mensagem dele. Outras falhas de worker terminam com status `Error` e um `metadata.error_code` não-RPT de `report_generation_failed`, `report_generation_timeout`, `report_generation_canceled` ou `report_message_schema_unsupported`. Essas falhas não têm mapa `sections`. Um relatório cujo worker parou de sinalizar que estava vivo termina com status `Error` e `metadata.error_code` `RPT-0160`.

| `code` | Descrição | Significado |
| - | - | :- |
| RPT-0058 | Fonte de dados indisponível | A fonte de dados está indisponível no momento. Os resultados podem estar incompletos. |
| RPT-0060 | Falha no job de extração | O job de extração falhou. Tente novamente mais tarde ou entre em contato com o suporte. |
| RPT-0061 | Falha na renderização do template | O template não pôde ser renderizado com os dados fornecidos. Este é um erro permanente e não terá sucesso em uma nova tentativa. |
| RPT-0063 | Chave de hash do CRM não configurada | Chave de hash do CRM não configurada. |
| RPT-0064 | Chave de criptografia do CRM não configurada | Chave de criptografia do CRM não configurada. |
| RPT-0065 | Falha na descriptografia do registro | Falha na descriptografia do registro. |
| RPT-0066 | Falha na inicialização da cifra | Falha na inicialização da cifra. |
| RPT-0067 | Dados extraídos inválidos | Os dados extraídos são inválidos. |
| RPT-0068 | Resultado de coleta inesperado | A coleta de dados retornou um resultado inesperado. |
| RPT-0069 | Fonte de dados não encontrada | A fonte de dados referenciada pelo relatório não foi encontrada. |
| RPT-0070 | Fonte de dados indisponível | A fonte de dados estava indisponível durante a extração. |
| RPT-0136 | Versão de esquema da mensagem de relatório não aceita | O worker recebeu uma mensagem de relatório escrita para uma versão de esquema mais nova do que ele aceita e a recusou. O relatório termina com status `Error` e `metadata.error_code` `report_message_schema_unsupported`. Gere o relatório de novo quando todos os workers estiverem na versão mais nova. |
| RPT-0160 | Worker do relatório perdido | O worker responsável pelo relatório parou de sinalizar que estava vivo, então o Reporter encerrou o relatório com status `Error`. Procure um worker parado ou travado. |
| RPT-0161 | Limite de linhas excedido | Uma seção de dados encontrou mais linhas do que o limite de linhas configurado na fonte de dados. A seção falha em vez de retornar um resultado truncado. Restrinja o filtro do relatório ou aumente o limite de linhas da fonte de dados. |
| RPT-0162 | Tempo limite de consulta da fonte de dados | A consulta de uma seção de dados não terminou dentro do tempo limite de consulta configurado na fonte de dados. Restrinja o filtro do relatório ou aumente o tempo limite de consulta da fonte de dados. |
| RPT-0195 | Nada para remeter | Um conjunto que o documento não pode remeter vazio, ou um conjunto fechado, não leu nenhuma linha. A mensagem diz o que cada consulta leu. Verifique o período, os filtros e o escopo da instituição, depois os próprios dados. |

## Erros de geração agendada (registrados em log)

***

O agendador de prazos gera estes códigos. Ele roda no Manager quando `DEADLINE_TRIGGER_ENABLED=true`. Ele não responde a nenhuma requisição, então os códigos aparecem apenas nas suas linhas de log, nunca em uma resposta HTTP. Cada código fica no campo `error_code` da sua linha de log, exceto o RPT-0113, que aparece apenas no campo `error`. Quando uma recusa não se resolve com uma nova tentativa, uma segunda linha a informa com `error_code` `RPT-0118` e carrega o código original em `error`.

| `code` | Descrição | Significado |
| - | - | - |
| RPT-0113 | Lembrete não nomeia template para ler a família | O prazo venceu, mas não nomeia template, então não há família de relatório para gerar. A ocorrência ainda é anunciada. Se o prazo deve produzir um relatório, informe um `templateId` cujo template tenha categoria. |
| RPT-0114 | Template sem família no disparo | O template do prazo não tem categoria quando o agendador o dispara, então nenhum relatório é gerado. Arquive o template em uma categoria. |
| RPT-0115 | Geração agendada não conseguiu verificar o tenant | O agendador não conseguiu confirmar o tenant dono do prazo, então não gravou nada. |
| RPT-0116 | Janela do lembrete não pôde ser resolvida no disparo | O agendador não conseguiu resolver a janela de dados da ocorrência, então nenhum relatório é gerado para ela. Salve o prazo de novo com uma janela que o Reporter conhece. |
| RPT-0117 | Geração agendada de relatório recusada | A geração de relatório recusou a requisição agendada. A linha de log carrega a recusa subjacente. |
| RPT-0118 | Geração agendada sem nova tentativa útil | Qualifica uma recusa que se repete em toda ocorrência até alguém alterar o prazo, o template ou o filtro. |
| RPT-0119 | Geração agendada esgotada | A mesma recusa se repetiu em ocorrências consecutivas, então o agendador parou de tentar gerar o relatório deste prazo. O anúncio continua sendo enviado. |
| RPT-0132 | Ocorrências agendadas puladas | Ocorrências venceram e foram puladas quando o agendador avançou. Cada ocorrência pulada não produziu relatório. É um aviso, não uma falha. |
| RPT-0133 | Recuperação agendada incompleta | O agendador produziu parte do backlog de um prazo, e a próxima execução continua de onde parou. `catch_up_stop_reason` é `tenant_budget_spent` (um aviso) ou `ceiling_reached` (um erro: investigue o atraso). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.