Erros

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}

{
  "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	400	falta um cabeçalho obrigatório (por exemplo, Idempotency-Key)
requisicao_invalida	400	corpo que não é JSON ou tipo de conteúdo errado
chave_ausente	401	problema com a chave
chave_invalida	401	problema com a chave
chave_vencida	401	problema com a chave
escopo_insuficiente	403	o plano permite, mas a chave não tem o escopo
fora_do_plano	403	o produto não está no plano da conta
arquivo_nao_encontrado	404	criarRelatorio com arquivo_id inexistente ou de empresa fora da conta
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	404	recurso por id que não existe ou não é da conta
rede_nao_encontrada	404	criarEmpresa com rede_id de fora da carteira
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	409	criarRelatorio com arquivo que ainda não está lido
cnpj_divergente	409	enviarArquivo de SPED com cnpj ou empresa_id que não bate com o CNPJ do arquivo
empresa_indisponivel	409	o CNPJ não pode ser cadastrado nesta conta; fale com a equipe. Substitui empresa_de_outra_conta
empresa_ja_cadastrada	409	o CNPJ já está na conta
estado_incompativel	409	a operação não se aplica ao estado do recurso (por exemplo, download antes de concluir)
idempotencia_em_andamento	409	mesma Idempotency-Key ainda em processamento
relatorio_ja_terminou	409	cancelamento de relatório terminado
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	413	lote de ICMS ou de NF-e com mais de 500 itens
arquivo_corrompido	422	ZIP que não abre ou com entrada de caminho relativo ou absoluto
empresa_nao_cadastrada	422	arquivo de CNPJ que não está na conta
idempotencia_conflito	422	mesma Idempotency-Key com outra impressão digital
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	422	fim antes do início, ou período fora do arquivo
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	422	captura na Receita sem procuração ou certificado com a equipe (em seguida, por plano)
tipo_incompativel_com_arquivo	422	o tipo de relatório não usa o arquivo informado
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	422	ECD e ECF no envio, até a correção da substituta
url_invalida	422	URL de webhook fora da regra
cota_diaria_excedida	429	limite por minuto ou cota do dia (inclusive empresas_dia e reenvios_dia)
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	429	limite por minuto ou cota do dia (inclusive empresas_dia e reenvios_dia)
erro_interno	500	falha da RMF
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	falha de relatório
cnpj_invalido	falha de leitura de arquivo
contagem_de_linhas_divergente	falha de leitura de arquivo
formato_nao_reconhecido	falha de leitura de arquivo
leitura_interrompida	falha de leitura de arquivo
nenhum_xml_valido	falha de leitura de ZIP de XML
procuracao_vencida	falha de consulta à Receita (em seguida, por plano)
receita_indisponivel	falha de consulta à Receita (em seguida, por plano)
sefaz_indisponivel	falha de lote de NF-e (em seguida, por plano)
sem_contrato	falha de leitura de arquivo
sem_movimento	falha de leitura de arquivo