Erros e limites

Formato dos erros

Todos os erros da API seguem o mesmo formato:

{ "code": "NOT_FOUND", "message": "CNPJ não encontrado.", "requestId": "9f2c..." }

Trate pelo code, não pela mensagem. Os textos podem mudar, os códigos não. Guarde o requestId no seu log: é por ele que o suporte localiza a chamada.

• Quando a chamada é recusada antes de chegar à consulta (401 e 429), o requestId pode vir null e o cabeçalho X-Request-Id pode não vir.
• Um erro gerado fora da API, na sua rede ou num proxy, pode chegar sem corpo JSON. Um cliente robusto confere o status HTTP e o Content-Type antes de ler o corpo.

Códigos

HTTP	code	O que fazer
400	INVALID_CNPJ	Formato ou dígito verificador inválido. Confira antes de reenviar
401	API_KEY_INVALID	Chave ausente, inválida, revogada ou expirada. Não repita a chamada
403	INSUFFICIENT_BALANCE	Sem saldo e sem franquia disponível. Recarregue a carteira no app
404	NOT_FOUND	CNPJ não encontrado na base
408	CNPJ_LOOKUP_TIMEOUT	A consulta demorou demais. Pode repetir
429	RATE_LIMITED	Reduza o ritmo. Respeite o cabeçalho Retry-After
500	INTERNAL_ERROR	Erro inesperado. Repita com espera crescente e, se persistir, fale com o suporte informando o requestId
503	CNPJ_SOURCE_UNAVAILABLE	Base indisponível no momento. Pode repetir
503	SERVICE_UNAVAILABLE	A API está fora do ar ou reiniciando (resposta da borda). Pode repetir

Um caminho que não existe sob /v1 responde HTTP 404 sem o campo code.

Quando repetir

Em 408, 429, 500 e 503, repita a chamada com espera crescente (backoff). Nos demais códigos, repetir devolve o mesmo erro.

Repetir é seguro: a mesma consulta dentro de 24 horas não é cobrada de novo. Veja Preços e cobrança.

Limites

Limite	Valor
Por chave	10 requisições por segundo
Por IP	20 requisições por segundo, com pico de 40

Acima do limite, a API responde 429 RATE_LIMITED.

Cabeçalhos da resposta

Cabeçalho	Conteúdo
X-Request-Id	Identificador da chamada, para o suporte
X-Toreva-Charged	true quando a consulta contou como consulta cobrável, seja debitada do saldo, seja coberta pela franquia do mês; false quando o mesmo CNPJ é reconsultado dentro de 24 horas
X-Toreva-Balance-Cents	Saldo restante da carteira, em centavos. Vem nas respostas 200