# Erros

> Formato dos erros (application/problem+json), o campo codigo e a lista de todos os códigos.

Toda resposta de erro vem em `application/problem+json` (RFC 9457), com estes campos:

| Campo | O que é |
|---|---|
| `type` | URL da página do erro neste portal, por exemplo `https://docs.rmfestrategia.com/erros/limite_excedido` |
| `title` | Título curto |
| `status` | Status HTTP |
| `detail` | O que fazer, em português. Nunca explica como a RMF calculou |
| `instance` | O caminho chamado |
| `codigo` | Código estável, em `snake_case`. **Decida por ele**, nunca pelo texto |
| `request_id` | Identificador da chamada, igual ao cabeçalho `X-Request-Id`. Guarde-o e informe ao suporte |
| `erros` | Só no 422: lista de `{campo, mensagem}` |

```json
{
  "type": "https://docs.rmfestrategia.com/erros/limite_excedido",
  "title": "Limite excedido",
  "status": 429,
  "detail": "Você passou do limite de chamadas por minuto. Tente de novo em 23 segundos.",
  "instance": "/v1/icms/aliquotas",
  "codigo": "limite_excedido",
  "request_id": "req_01JC8FBG6R8V2X5Z9C3E7HKMNP"
}
```

Código que você não conhece: trate como falha genérica do mesmo status HTTP. Lista vazia não é erro: é 200 com `dados: []`. Recurso de outra conta responde sempre 404.

## Códigos de resposta HTTP (`codigo`)

| `codigo` | HTTP | Quando |
|---|---|---|
| [`cabecalho_ausente`](/erros/cabecalho_ausente) | 400 | falta um cabeçalho obrigatório (por exemplo, `Idempotency-Key`) |
| [`requisicao_invalida`](/erros/requisicao_invalida) | 400 | corpo que não é JSON ou tipo de conteúdo errado |
| [`chave_ausente`](/erros/chave_ausente) | 401 | problema com a chave |
| [`chave_invalida`](/erros/chave_invalida) | 401 | problema com a chave |
| [`chave_vencida`](/erros/chave_vencida) | 401 | problema com a chave |
| [`escopo_insuficiente`](/erros/escopo_insuficiente) | 403 | o plano permite, mas a chave não tem o escopo |
| [`fora_do_plano`](/erros/fora_do_plano) | 403 | o produto não está no plano da conta |
| [`arquivo_nao_encontrado`](/erros/arquivo_nao_encontrado) | 404 | `criarRelatorio` com `arquivo_id` inexistente ou de empresa fora da conta |
| [`nao_encontrado`](/erros/nao_encontrado) | 404 | o caminho não existe na API (por exemplo, um erro de digitação na URL); não é recurso de conta |
| [`recurso_nao_encontrado`](/erros/recurso_nao_encontrado) | 404 | recurso por id que não existe ou não é da conta |
| [`rede_nao_encontrada`](/erros/rede_nao_encontrada) | 404 | `criarEmpresa` com `rede_id` de fora da carteira |
| [`metodo_nao_permitido`](/erros/metodo_nao_permitido) | 405 | o caminho existe, mas não aceita o método usado; o cabeçalho `Allow` lista os aceitos |
| [`arquivo_nao_processado`](/erros/arquivo_nao_processado) | 409 | `criarRelatorio` com arquivo que ainda não está `lido` |
| [`cnpj_divergente`](/erros/cnpj_divergente) | 409 | `enviarArquivo` de SPED com `cnpj` ou `empresa_id` que não bate com o CNPJ do arquivo |
| [`empresa_indisponivel`](/erros/empresa_indisponivel) | 409 | o CNPJ não pode ser cadastrado nesta conta; fale com a equipe. Substitui `empresa_de_outra_conta` |
| [`empresa_ja_cadastrada`](/erros/empresa_ja_cadastrada) | 409 | o CNPJ já está na conta |
| [`estado_incompativel`](/erros/estado_incompativel) | 409 | a operação não se aplica ao estado do recurso (por exemplo, download antes de concluir) |
| [`idempotencia_em_andamento`](/erros/idempotencia_em_andamento) | 409 | mesma `Idempotency-Key` ainda em processamento |
| [`relatorio_ja_terminou`](/erros/relatorio_ja_terminou) | 409 | cancelamento de relatório terminado |
| [`arquivo_grande_demais`](/erros/arquivo_grande_demais) | 413 | arquivo acima do limite, inclusive ZIP acima dos limites de descompactação ou de quantidade de XML. Recusado pelo `Content-Length` antes da leitura; quando quem corta é o Caddy, o `request_id` é `req_<UUID>` |
| [`lote_grande_demais`](/erros/lote_grande_demais) | 413 | lote de ICMS ou de NF-e com mais de 500 itens |
| [`arquivo_corrompido`](/erros/arquivo_corrompido) | 422 | ZIP que não abre ou com entrada de caminho relativo ou absoluto |
| [`empresa_nao_cadastrada`](/erros/empresa_nao_cadastrada) | 422 | arquivo de CNPJ que não está na conta |
| [`idempotencia_conflito`](/erros/idempotencia_conflito) | 422 | mesma `Idempotency-Key` com outra impressão digital |
| [`parametro_invalido`](/erros/parametro_invalido) | 422 | parâmetro ou corpo fora da validação (inclusive CNPJ com DV inválido e ZIP de XML sem `cnpj` nem `empresa_id`) |
| [`periodo_invalido`](/erros/periodo_invalido) | 422 | fim antes do início, ou período fora do arquivo |
| [`periodo_longo`](/erros/periodo_longo) | 422 | consulta de ICMS acima de 240 meses. Reservado: a base de ICMS (de 2021-01 até o mês corrente mais 12) cabe em bem menos de 240 meses, então hoje o código não ocorre; um período fora da base é `parametro_invalido` |
| [`procuracao_ausente`](/erros/procuracao_ausente) | 422 | captura na Receita sem procuração ou certificado com a equipe (em seguida, por plano) |
| [`tipo_incompativel_com_arquivo`](/erros/tipo_incompativel_com_arquivo) | 422 | o tipo de relatório não usa o arquivo informado |
| [`tipo_indisponivel`](/erros/tipo_indisponivel) | 422 | tipo de relatório que não está no catálogo da conta; o `detail` diz o motivo (fora do plano, exige a planilha de resultado no plano ou ainda não liberado) |
| [`tipo_nao_suportado`](/erros/tipo_nao_suportado) | 422 | ECD e ECF no envio, até a correção da substituta |
| [`url_invalida`](/erros/url_invalida) | 422 | URL de webhook fora da regra |
| [`cota_diaria_excedida`](/erros/cota_diaria_excedida) | 429 | limite por minuto ou cota do dia (inclusive `empresas_dia` e `reenvios_dia`) |
| [`limite_de_recusas_excedido`](/erros/limite_de_recusas_excedido) | 429 | mais de 50 envios recusados no dia por `empresa_nao_cadastrada` ou `arquivo_corrompido` (`enviarArquivo`; o `detail` diz qual pesou) ou mais de 100 chaves `fora_da_conta` (`criarLoteNotas`, depois do lançamento) |
| [`limite_excedido`](/erros/limite_excedido) | 429 | limite por minuto ou cota do dia (inclusive `empresas_dia` e `reenvios_dia`) |
| [`erro_interno`](/erros/erro_interno) | 500 | falha da RMF |
| [`servico_indisponivel`](/erros/servico_indisponivel) | 503 | o serviço está fora do ar ou reiniciando; quem responde é o servidor de entrada, antes de a chamada chegar à API. Quando a própria API não consegue atender na hora (serviço de apoio ou banco ocupado), ela também responde 503, com `erro_interno` e `Retry-After`. Tente de novo com espera (respeite `Retry-After` quando vier) |

## Códigos de falha de job, relatório e arquivo (`erro.codigo`)

Vêm dentro do recurso, quando o `estado` é `falhou` ou o arquivo foi `rejeitado`.

| `codigo` | Quando |
|---|---|
| [`arquivo_faltando`](/erros/arquivo_faltando) | falha de relatório |
| [`cnpj_invalido`](/erros/cnpj_invalido) | falha de leitura de arquivo |
| [`contagem_de_linhas_divergente`](/erros/contagem_de_linhas_divergente) | falha de leitura de arquivo |
| [`formato_nao_reconhecido`](/erros/formato_nao_reconhecido) | falha de leitura de arquivo |
| [`leitura_interrompida`](/erros/leitura_interrompida) | falha de leitura de arquivo |
| [`nenhum_xml_valido`](/erros/nenhum_xml_valido) | falha de leitura de ZIP de XML |
| [`procuracao_vencida`](/erros/procuracao_vencida) | falha de consulta à Receita (em seguida, por plano) |
| [`receita_indisponivel`](/erros/receita_indisponivel) | falha de consulta à Receita (em seguida, por plano) |
| [`sefaz_indisponivel`](/erros/sefaz_indisponivel) | falha de lote de NF-e (em seguida, por plano) |
| [`sem_contrato`](/erros/sem_contrato) | falha de leitura de arquivo |
| [`sem_movimento`](/erros/sem_movimento) | falha de leitura de arquivo |