Errores

Ninguna respuesta 4xx o 5xx consume crédito ni genera cobro de excedente.

Formato del error

Todo error viene en JSON con error y, en la mayoría de los casos, message. Algunos traen también code, el valor estable para tratar en su código.

402 Payment Required

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

Estado	Error	Cuándo ocurre	Qué hacer
400	Invalid CPF format	El CPF no tiene 11 dígitos numéricos.	Corrija el CPF antes de reenviar.
400	Invalid birthdate	birthdate ausente o fuera del formato AAAA-MM-DD.	Envíe una fecha válida.
400	INVALID_BATCH · INVALID_QUERY	Lote vacío, con más de 1.000 elementos o mal formado; o parámetros de paginación inválidos.	Ajuste el cuerpo o la query.
401	Invalid or missing API key	Encabezado x-api-key ausente, clave inválida o revocada, o clave de otro entorno (código WRONG_ENVIRONMENT).	Revise la clave en el panel.
402	CREDITS_EXHAUSTED	Plan gratuito sin créditos en el ciclo, o lote mayor que el saldo.	Espere la renovación o contrate un plan.
403	ACCOUNT_BLOCKED	Cuenta suspendida o bloqueada.	Hable con soporte.
404	CPF not found	CPF válido, pero sin coincidencia en la fuente oficial (o fecha de nacimiento distinta).	Es un resultado normal. No reintente con los mismos datos.
400	INVALID_DOCUMENT	Validación de documento: el cuerpo no trae `document` como texto.	Envíe el CPF o el CNPJ en el campo document.
400	INVALID_CNPJ_FORMAT	El CNPJ no tiene 14 caracteres o los dígitos verificadores no coinciden.	Corrija el CNPJ. Para solo comprobar el número, use `POST /v1/validate`.
404	CNPJ not found	CNPJ válido, pero sin registro en los Datos Abiertos (código CNPJ_NOT_FOUND).	Es un resultado normal. No reintente con los mismos datos.
404	BATCH_NOT_FOUND	Lote inexistente, de otra cuenta o vencido (24 horas).	Envíe el lote de nuevo.
422	Invalid check digit	Los dígitos verificadores del CPF no coinciden.	Corrija el CPF.
429	Rate limit exceeded	Superó el límite de solicitudes por segundo del plan.	Espere el tiempo del encabezado `Retry-After`.
429	Too many attempts for this CPF	Se probaron demasiadas fechas de nacimiento distintas para este CPF (código CPF_ATTEMPTS_EXCEEDED). El bloqueo vale solo para ese CPF.	Confirme la fecha de nacimiento con el titular y espere el tiempo de `Retry-After`. No se cobra crédito.
429	Too many unsuccessful lookups	La cuenta tuvo demasiadas consultas sin resultado (404) en poco tiempo (código ACCOUNT_MISS_BUDGET_EXCEEDED).	Valide los datos antes de consultar y espere `Retry-After`. Si es un error, hable con soporte.
429	Batch rate limit exceeded / Too many batches in progress	Los lotes enviaron demasiados ítems por minuto o hay demasiados ítems esperando procesamiento (códigos BATCH_RATE_LIMITED y BATCH_BACKLOG).	Espere a que terminen los lotes en curso y envíe el siguiente.
500 · 503	Service unavailable	Falla temporal en la infraestructura o en la fuente oficial.	Reintente con intervalos crecientes.