Limitaciones

La API Comercial atiende hasta 500 solicitudes por minuto por suscripción. El límite vale para todos los endpoints autenticados y cuenta toda solicitud, independientemente de que la consulta haya encontrado el CNPJ.

El conteo usa una ventana deslizante de 60 segundos: no existe un cambio de minuto que reinicie el contador. Cada solicitud deja de contar 60 segundos después de realizada.

Además del límite de la suscripción, existe un límite por IP, que suma las solicitudes de todas las suscripciones que llaman a la API desde la misma dirección. El límite por IP nunca es menor que el de su suscripción: una suscripción que llama a la API sola desde una dirección alcanza primero su propio límite.

Al superar cualquiera de los límites, la API responde con el código de estado HTTP 429:

{
  "status": 429,
  "titulo": "Muitas requisições",
  "detalhes": "Excedido o limite máximo de 500 requisições por minuto por assinatura. Liberação ocorrerá em 13/10/2026, 11:47:12",
  "validacao": []
}

El horario de liberación viene solo como texto en portugués dentro de detalhes, en horario de Brasilia. La respuesta no incluye el header Retry-After. Al recibir un 429, espere 60 segundos antes de intentar de nuevo y no interprete el texto de detalhes.

Buenas prácticas

• Controle el ritmo de su lado. Distribuya las llamadas a lo largo del minuto en vez de dispararlas todas a la vez.
• Limite la concurrencia. Muchas solicitudes en paralelo agotan el límite en segundos.
• Use backoff al recibir 429. Repetir la llamada inmediatamente solo prolonga el bloqueo.
• Evite consultas repetidas. Guarde en su sistema el resultado de los CNPJs ya consultados.

Límite mensual

El límite por minuto es independiente del límite de consultas mensuales del plan contratado. Para seguir el consumo del período, use el endpoint de consumo.