Erros e retentativas

Resumo

400: chamada inválida

Parâmetro desconhecido na contagem

A contagem de empresas recebeu uma chave que não conhece. A mensagem lista até cinco chaves recusadas. Não conta na cota.

{"error": "invalid_filter", "message": "Parâmetro desconhecido: cidade"}

Agrupamento fora da lista

O group_by não está entre os aceitos. A mensagem traz os valores aceitos, um conjunto na contagem de empresas e outro na de obras. Conta 1 chamada.

{"error": "Invalid group_by", "message": "Allowed values: uf, cod_municipio, cnae_fiscal, cnae_divisao, cnae_grupo, cnae_classe, porte, situacao_cadastral, opc_simples, opc_mei, cod_nat_juridica, data_inicio_atividade, matriz_filial, bairro"}

{"error": "Invalid group_by", "message": "Allowed values: uf, cod_municipio, situacao, tipo_responsavel, qualificacao_responsavel, data_inicio_year"}

Parâmetros do ranking

Faltou cnae_fiscal e cod_municipio, ou opc_mei veio com valor diferente de 0. Conta 1 chamada.

{"error": "Missing filter", "message": "Informe ao menos um dos filtros: cnae_fiscal ou cod_municipio"}
{"error": "Invalid opc_mei", "message": "O único valor aceito para opc_mei é 0 (exclui optantes pelo MEI)"}

401: autenticação

Token ausente, inválido, vencido ou desativado. Não conta na cota. Corrija o token antes de chamar de novo; veja Autenticação.

{"error": "Unauthorized", "message": "Missing authentication token"}
{"error": "Unauthorized", "message": "Invalid or expired token"}
{"error": "Unauthorized", "message": "Company not found"}

403: acesso negado

Conta sem acesso

Conta sem assinatura ativa ou com pagamento em atraso. Não conta na cota. A chamada volta a funcionar com o pagamento confirmado.

{"error": "Forbidden", "message": "Account is not active or payment is overdue"}

Cota do mês esgotada

Não repita: a cota só volta no mês seguinte. Espere a renovação ou mude de plano. Não conta na cota.

{"error": "Monthly Quota Exceeded", "message": "You have reached your monthly API call limit for this billing period."}

Plano sem as buscas

Contagem, ranking e contagem de obras não estão liberados no plano da conta. Não conta na cota.

{"error": "Forbidden", "message": "Search endpoints are not enabled for your plan"}

Filtro recusado na contagem

A combinação de filtros da contagem de empresas foi recusada. O valor de errors é um texto com JSON dentro: leia como texto e decodifique. Conta 1 chamada.

{"errors": "{\"base\":[\"...\"]}"}

404: CNPJ fora da base

O CNPJ não está na base ou foi removido a pedido. Conta 1 chamada. Não repita a mesma consulta.

{"error": "Record not Found"}

422: combinação de filtros de obras

Na contagem de obras, cno ou ni_responsavel não combinam com situacao ou cnae_responsavel. Conta 1 chamada.

{"error": "Unsupported filter combination", "message": "cno/ni_responsavel cannot be combined with situacao/cnae_responsavel"}

429: limite por minuto

A conta passou do limite por minuto do plano ou do limite próprio das buscas. Não conta na cota. A resposta não diz quanto esperar: use a espera crescente abaixo. Em rajadas muito fortes, a proteção da plataforma também responde 429, com o corpo em texto simples.

{"error": "Rate Limit Exceeded", "message": "Too many requests. Please try again later."}

500: erro inesperado

Pode contar 1 chamada, conforme o ponto da falha. Repita com espera crescente e, se continuar, reporte o problema.

{"error": "Internal Server Error", "message": "An unexpected error occurred. Please try again later."}

503: indisponível por um tempo

Base em atualização: conta 1 chamada. Espere alguns minutos e repita.

{"error": "Base sendo atualizada, aguarde alguns minutos e tente novamente."}

Consulta que demorou demais: o primeiro corpo vem das operações de empresas (ficha, contagem e ranking) e pode contar 1 chamada; o segundo vem do ranking e da contagem de obras e conta 1 chamada. Repita com espera crescente.

{"error": "Service Unavailable", "message": "The database query took too long. Please try again later."}
{"error": "Request took too long to process"}

Retentativas

• Repita só 429, 500 e 503. Os demais códigos não mudam sem você corrigir a chamada, o token, a conta ou esperar o mês seguinte.
• Espere cada vez mais: 1 segundo, 2 segundos, 4 segundos. Faça no máximo três novas tentativas e registre o erro.
• Não há cabeçalho de espera na resposta, nem Retry-After nem contador de limite.
• Não repita 403 de cota, de conta ou de filtro recusado: a resposta será a mesma.

import time
import requests


def chamar(url, headers, tentativas=3):
    espera = 1
    for tentativa in range(tentativas + 1):
        resposta = requests.get(url, headers=headers, timeout=30)
        if resposta.status_code not in (429, 500, 503) or tentativa == tentativas:
            return resposta
        time.sleep(espera)
        espera *= 2