Começando

Erros e limites

A API prefere recusar com motivo a responder com palpite. Esta página lista cada status, o que ele significa e o que fazer a respeito.

Formato do erro

Erros voltam como JSON com o campo detail — uma frase em português dizendo o motivo e, quando aplicável, o campo ou a regra envolvida:

Exemplo · 404

{
  "detail": "Nenhuma regra de ICMS-ST aprovada e vigente para NCM 22021000 em SP->MG na data 2026-08-01."
}

Status por situação

Status	Significado e remédio
400 / 422	Payload inválido: campo faltando, tipo errado, `tributo` fora do contrato, UF inexistente. O `detail` nomeia o campo — corrija o payload.
401	Credencial ausente, vencida ou token inválido. Verifique o header `X-API-Key`; se a chave expirou, crie ou rotacione outra no painel.
402	Bloqueio comercial: assinatura suspensa/cancelada, teto de excedente atingido ou cortesia de sandbox esgotada no ciclo. Não adianta retentar — resolva no painel (pagamento, troca de plano) ou aguarde o ciclo virar.
403	Chave desconhecida/revogada, conta inativa ou escopo insuficiente. Confira qual chave a instância está usando.
404	Não há regra aprovada e vigente para os parâmetros pedidos (tributo, recorte geográfico, NCM, data). Não é erro do seu payload — é cobertura de conteúdo. Fale com a gente para priorizar o recorte que você precisa.
422 (regra)	O payload é válido e existe regra, mas o cálculo foi recusado com motivo — ver a seção fail-inert abaixo.
429	Rate limit do plano excedido (janela por minuto, por conta). Respeite o header `Retry-After` (segundos) e aplique backoff no seu cliente.
5xx / 503	Falha nossa ou dependência fora. `503` em autenticação significa que não conseguimos verificara credencial — nunca degradamos para "deixa passar". Retente com backoff exponencial.

O 422 fail-inert — por que a API recusa em vez de chutar

Um cálculo errado com citação legal anexada é pior que nenhum cálculo: parece auditável e não é. Por isso o motor recusa, nomeando o motivo, sempre que não pode afirmar o resultado:

Campo material ausente no payload — ex.: a regra aplicável usa pauta fiscal/PMPF (base = valor de pauta × quantidade) e o payload não trouxe quantidade; ou a regra de PIS/COFINS que casou discrimina o comprador e venda_a não foi declarado.
Operação fora do escopo modelado — ex.: ICMS próprio para optante do Simples Nacional, ou DIFAL de consumidor final. A recusa diz exatamente qual eixo está fora.
Regra publicada com conteúdo defeituoso — a regra existe, mas seu dado não sustenta o cálculo. A resposta identifica a regra (rule_code + versão) para você reportar; a correção é uma nova versão validada.

Trate 404 e 422 como respostas finais, não como erros transitórios: retentar o mesmo payload devolve o mesmo resultado. O caminho é corrigir o payload, ou falar com a gente sobre cobertura.

Rate limit e cota

Rate limit — requisições por minuto, por conta, conforme o plano (Starter 120, Growth 600, Scale 3.000, Enterprise dedicado). Estouro responde 429 + Retry-After.
Cota mensal — chamadas faturáveis do ciclo. A API não para no estouro da cota: o excedente é cobrado por chamada na fatura seguinte, com aviso em 80%. O que bloqueia (402) é o teto de excedente — um disjuntor de custo, configurável por conta.
Sandbox — 1.000 chamadas/mês de cortesia com chave fs_test_; esgotada, 402 até o ciclo virar (ou use fs_live_).

Postura de falha da nossa infra

Autenticação é fail-closed: sem conseguir provar a credencial, a resposta é 503. Rate limit e cota são fail-open: se o nosso contador cair, a sua chamada passa — jamais derrubamos a sua integração por falha da nossa infraestrutura de medição.