Erros

Nenhuma resposta 4xx ou 5xx consome crédito nem gera cobrança de excedente.

Formato do erro

Todo erro vem em JSON com error e, na maioria dos casos, message. Alguns trazem também code, que é o valor estável para tratar no seu código.

402 Payment Required

1{2 "error": "Payment Required",3 "message": "Limite de créditos excedido",4 "code": "CREDITS_EXHAUSTED"5}

Status	Erro	Quando acontece	O que fazer
400	Invalid CPF format	O CPF não tem 11 dígitos numéricos.	Corrija o CPF antes de reenviar.
400	Invalid birthdate	birthdate ausente ou fora do formato AAAA-MM-DD.	Envie uma data válida.
400	INVALID_BATCH · INVALID_QUERY	Lote vazio, com mais de 1.000 itens ou mal formado; ou parâmetros de paginação inválidos.	Ajuste o corpo ou a query.
401	Invalid or missing API key	Cabeçalho x-api-key ausente, chave inválida ou revogada, ou chave de outro ambiente (código WRONG_ENVIRONMENT).	Confira a chave no painel.
402	CREDITS_EXHAUSTED	Plano gratuito sem créditos no ciclo, ou lote maior que o saldo.	Aguarde a renovação ou contrate um plano.
403	ACCOUNT_BLOCKED	Conta suspensa ou bloqueada.	Fale com o suporte.
404	CPF not found	CPF válido, mas sem correspondência na fonte oficial (ou data de nascimento divergente).	É um resultado normal. Não tente de novo com os mesmos dados.
400	INVALID_DOCUMENT	Validação de documento: o corpo não traz `document` como texto.	Envie o CPF ou o CNPJ no campo document.
400	INVALID_CNPJ_FORMAT	O CNPJ não tem 14 caracteres ou os dígitos verificadores não conferem.	Corrija o CNPJ. Para só conferir o número, use `POST /v1/validate`.
404	CNPJ not found	CNPJ válido, mas sem registro nos Dados Abertos (código CNPJ_NOT_FOUND).	É um resultado normal. Não tente de novo com os mesmos dados.
404	BATCH_NOT_FOUND	Lote inexistente, de outra conta ou expirado (24 horas).	Envie o lote novamente.
422	Invalid check digit	Os dígitos verificadores do CPF não conferem.	Corrija o CPF.
429	Rate limit exceeded	Você passou do limite de requisições por segundo do plano.	Espere o tempo do cabeçalho `Retry-After`.
429	Too many attempts for this CPF	Datas de nascimento diferentes demais foram testadas para este CPF (código CPF_ATTEMPTS_EXCEEDED). A trava vale só para esse CPF.	Confira a data de nascimento com o titular e espere o tempo do `Retry-After`. Não cobra crédito.
429	Too many unsuccessful lookups	A conta teve consultas sem resultado (404) demais em pouco tempo (código ACCOUNT_MISS_BUDGET_EXCEEDED).	Valide os dados antes de consultar e espere o `Retry-After`. Se for engano, fale com o suporte.
429	Batch rate limit exceeded / Too many batches in progress	Os lotes enviaram itens demais por minuto ou há itens demais aguardando processamento (códigos BATCH_RATE_LIMITED e BATCH_BACKLOG).	Espere os lotes em andamento terminarem e envie o próximo.
500 · 503	Service unavailable	Falha temporária na infraestrutura ou na fonte oficial.	Tente de novo com intervalo crescente.