Tratamento de Erros

A FiscalAPI segue o formato RFC 7807 Problem Detail para todas as respostas de erro. Isso garante uma estrutura consistente e previsível para tratamento de erros em qualquer linguagem.

Formato da resposta de erro

{
  "type": "urn:fiscalapi:error:parametro_ausente",
  "title": "PARAMETRO_AUSENTE",
  "status": 400,
  "detail": "Informe pelo menos um parametro: cpf, cnpj ou ie",
  "instance": "https://api.fiscalapi.com.br/api/consultar",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-20T10:30:00Z"
}

Campos do erro

Campo	Tipo	Descrição
`type`	string	URI identificador do tipo de erro
`title`	string	Código do erro
`status`	integer	HTTP status code
`detail`	string	Descrição legível do erro
`instance`	string	URL da requisição que causou o erro
`request_id`	string	ID único da requisição
`timestamp`	string	Data/hora do erro em ISO 8601

Erros do Cliente (4xx)

Código	Status	Descrição
`PARAMETRO_AUSENTE`	400	Parâmetro obrigatório não informado
`PARAMETRO_CONFLITANTE`	400	Mais de um documento informado (envie apenas um)
`DOCUMENTO_INVALIDO`	400	CPF, CNPJ ou IE com formato inválido
`UF_NAO_SUPORTADA`	400	Estado não suportado para este endpoint
`IE_NAO_SUPORTADO`	400	Parâmetro IE não suportado (use cpf ou cnpj)
`INVALID_CREDENTIALS`	401	API Key inválida ou ausente
`RATE_LIMIT_EXCEEDED`	429	Limite de requisições excedido

Erros do Servidor (5xx)

Código	Status	Descrição
`ERRO_INTERNO`	500	Erro interno do servidor
`PROCESSAMENTO_FALHOU`	502	Falha ao processar a consulta no estado
`TODAS_FONTES_FALHARAM`	502	Todas as fontes de dados falharam
`SITE_INDISPONIVEL`	503	Portal da SEFAZ temporariamente indisponível

Boas práticas

Sempre verifique o status code antes de processar o corpo da resposta
Use o request_id ao entrar em contato com o suporte (contato@fiscalapi.com.br) para agilizar a investigação
Para erros 429, respeite o header Retry-After antes de reenviar a requisição
Para erros 502/503, implemente retry com backoff exponencial — a SEFAZ pode estar temporariamente fora do ar
Para erros 400, corrija os parâmetros da requisição antes de reenviar

Exemplo de tratamento de erros

const response = await fetch(url, {
  headers: { "X-API-Key": "fapi_sua_chave_aqui" },
});

if (!response.ok) {
  const error = await response.json();
  console.error(`[${error.title}] ${error.detail}`);

  switch (error.status) {
    case 400:
      // Corrija os parametros da requisicao
      throw new Error(`Parametro invalido: ${error.detail}`);
    case 401:
      // API Key invalida — verifique suas credenciais
      throw new Error("Credenciais invalidas");
    case 429:
      // Limite excedido — aguarde e tente novamente
      const retryAfter = response.headers.get("Retry-After");
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      // Reenviar requisicao...
      break;
    case 502:
    case 503:
      // Fonte indisponivel — retry com backoff exponencial
      break;
    default:
      throw new Error(`Erro inesperado: ${error.detail}`);
  }
}

const data = await response.json();

import requests
import time

response = requests.get(url, headers={"X-API-Key": "fapi_sua_chave_aqui"})

if not response.ok:
    error = response.json()
    print(f"[{error['title']}] {error['detail']}")

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        time.sleep(retry_after)
        # Reenviar requisicao...
    elif response.status_code in (502, 503):
        # Retry com backoff exponencial
        pass
    elif response.status_code == 400:
        raise ValueError(f"Parametro invalido: {error['detail']}")
    elif response.status_code == 401:
        raise PermissionError("API Key invalida")

data = response.json()

$response = Http::withHeaders([
    'X-API-Key' => 'fapi_sua_chave_aqui',
])->get($url);

if ($response->failed()) {
    $error = $response->json();
    Log::error("[{$error['title']}] {$error['detail']}");

    if ($response->status() === 429) {
        $retryAfter = $response->header('Retry-After') ?? 60;
        sleep((int) $retryAfter);
        // Reenviar requisicao...
    }
}

$data = $response->json();

Sempre inclua o request_id ao reportar problemas ao suporte (contato@fiscalapi.com.br). Isso permite localizar sua requisição nos logs do servidor imediatamente.

Esta pagina foi util?