Erros e respostas da API

As consultas da Sintegrapi não usam um único formato de erro. O corpo depende da etapa que encerrou a requisição e da rota consultada. Verifique o status HTTP e o corpo, quando houver; uma resposta HTTP 200 também pode representar ausência de dados ou uma falha informada no resultado.

Os exemplos abaixo reproduzem os formatos e mensagens gerados pela API. request_id e traceId variam a cada requisição. Campos opcionais podem ser omitidos. Para os comportamentos específicos da consulta CPF, veja os retornos do CPF SERPRO.

Erros e consumo de créditos

O status HTTP sozinho não determina a cobrança. Uma consulta concluída pode informar ausência de certidão negativa. Da mesma forma, success=false ou a presença de error_message não significam, por si só, erro sem cobrança.

Falhas online do CPF não são cobradas. Sem cadastro utilizável e sem fallback, o retorno é HTTP 503, com success=false e error=true no layout SINTEGRAPI. No SERPRO, o código e a mensagem ficam na raiz. Créditos reservados são devolvidos na finalização; veja o corpo exato dos dois layouts.

Consulte a seção Custos de cada operação e o consumo registrado no painel. A CND Estadual e a CND Federal custam 1 crédito no cache ou 3 online. O CPF custa 1 crédito na modalidade cache ou 10 na modalidade online; o fallback após tentativa online pode manter o custo online.

Formatos de resposta

Não há um campo code obrigatório para todos os erros. Quando existir, trate-o conforme a documentação da consulta: ele pode ser uma string numérica, como "400", ou um código próprio daquela rota. error_message.code não substitui o status HTTP: os dois podem ter valores diferentes.

O parâmetro format do CPF seleciona o layout do resultado. Ele não transforma as respostas de autenticação, validação, acesso, saldo ou limite de uso em um layout único.

400 — documento inválido

Um CPF inválido é rejeitado antes da consulta. Exemplo de resposta de GET /consultas/v2/cpf-rfb/CPF_INVALIDO:

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "CPF inválido."
  }
}

Corrija o documento antes de repetir. Nesse retorno, error_message.code não é incluído.

400 — parâmetro inválido

Na consulta CPF, date_format=yyyyMMdd é rejeitado porque os formatos de saída aceitos são ddMMyyyy e yyyy-MM-dd:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "date_format": ["Formato de data inválido. Use ddMMyyyy ou yyyy-MM-dd."]
  },
  "traceId": "11111111-1111-4111-8111-111111111111"
}

Esse corpo não possui request_id, success, error nem error_message. Leia as mensagens de cada parâmetro em errors.

Nem toda validação usa esse formato. Por exemplo, cache_strategy=INVALIDA na consulta CPF retorna:

{
  "message": "parâmetro cache_strategy inválido (INVALIDA). Valores possíveis: CACHE_SE_EXISTIR, CACHE_PREFERENCIAL, SO_ONLINE, SO_CACHE, ONLINE_PREFERENCIAL. Veja documentação para mais detalhes. O valor default é: CACHE_PREFERENCIAL",
  "code": "400"
}

A mensagem acima é a mensagem atual do validador. Na rota CPF, omitir cache_strategy usa SO_CACHE; enviar o parâmetro vazio utiliza CACHE_PREFERENCIAL.

HTTP 400 também pode representar falha de consulta

Não interprete todo HTTP 400 como erro de preenchimento. Nas CNDs, falhas técnicas também podem retornar esse status, com error=true e sem cobrança. Leia a mensagem para distinguir uma entrada inválida de uma indisponibilidade.

Na CND Federal, SO_CACHE sem certidão válida retorna HTTP 400, diferentemente do HTTP 404 usado pelo CPF sem cadastro em cache:

{
  "source": "",
  "billing": {
    "credits": 0,
    "source": ""
  },
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "Não há uma certidão válida no cache da SintegrAPI para esta consulta.",
    "code": "CACHE_NAO_ENCONTRADO"
  }
}

Nesse caso, reveja a estratégia de consulta da CND Federal. Para buscar na fonte, selecione uma modalidade que permita consulta online e considere seu custo.

401 — chave de API ausente ou inválida

Nas rotas autenticadas por x-api-key, a falha de autenticação retorna HTTP 401 com corpo vazio:

HTTP/1.1 401 Unauthorized

Confira o header x-api-key e a validade da chave. Não tente converter um corpo vazio em JSON nem espere mensagens como Missing API Key no corpo: elas não são retornadas por esse fluxo.

402 — saldo insuficiente

A consulta é interrompida quando não há saldo suficiente para a modalidade necessária. Exemplo:

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "Saldo insuficiente. Por gentileza, adicione saldo para continuar a consultar."
  }
}

Confira o saldo e o custo da modalidade antes de repetir. Na consulta CPF, esse mesmo envelope pode ser retornado mesmo com format=SERPRO.

403 — consulta não habilitada

Uma chave válida não garante acesso a todas as consultas. Na consulta CPF, a falta de habilitação retorna somente a mensagem na raiz:

{
  "message": "Esta consulta não está inclusa no seu modelo de negócio atual. Para habilitar o acesso ou conhecer as opções disponíveis, entre em contato com a nossa equipe comercial."
}

Outras restrições de acesso podem usar o envelope de consulta. Por exemplo, uma consulta indisponível para contas que possuem apenas Free Tier pode responder:

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "Esta consulta não está disponível no plano Free Tier. Contrate um plano pago para utilizar este recurso."
  }
}

A mensagem e os requisitos de acesso dependem da consulta. Nenhum desses dois exemplos exige um campo code.

404 — resultado ou recurso não encontrado

O significado depende da consulta. No CPF com SO_CACHE, a ausência de cadastro é um erro sem cobrança:

{
  "serpro_result": {
    "code": "404",
    "message": "CPF não encontrado em cache."
  },
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "CPF não encontrado em cache.",
    "code": "404"
  },
  "cache": true
}

Com format=SERPRO, o corpo contém apenas code e message. cache=true no envelope acima identifica a modalidade executada, sem afirmar que houve cadastro encontrado.

Nas CNDs, HTTP 404 também pode indicar uma consulta concluída sem certidão negativa. Exemplo da CND Estadual:

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": false,
  "error_message": {
    "message": "A consulta foi concluída sem uma certidão disponível."
  }
}

Esse resultado fiscal é cobrado conforme a origem: 1 crédito no cache ou 3 online. Outros resultados fiscais podem incluir campos adicionais e a justificativa da fonte. Na CND Federal, consulte também certificate_type e billing.credits.

Uma rota ou um comprovante inexistente pode retornar HTTP 404 sem esse envelope. No CPF, a ausência de cadastro informada pela fonte online também retorna HTTP 404 com código e mensagem, sem cobrança. Uma indisponibilidade ou resposta inválida da fonte retorna HTTP 503, diferenciando falha de consulta de cadastro não encontrado.

409 — requisição já processada ou em andamento

Na CND Federal, uma repetição com chave de idempotência pode encontrar uma operação em andamento ou um resultado anterior que não está disponível para reenvio. Exemplo:

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "Uma requisição com esta chave de idempotência ainda está em processamento.",
    "code": "REQUISICAO_JA_PROCESSADA"
  }
}

O retorno de conflito não gera cobrança adicional. A operação original pode ser concluída e cobrada normalmente. Preserve a mesma Idempotency-Key ao repetir a mesma operação e siga as orientações de idempotência da CND Federal. Não troque a chave apenas para contornar o conflito, pois isso identifica uma nova operação.

429 — limites de uso

Há dois retornos diferentes que a integração deve aceitar.

Limite de frequência: quando o limite de requisições por período é atingido, o retorno é HTTP 429 com corpo vazio. Reduza a frequência e aguarde a renovação da janela de uso.

HTTP/1.1 429 Too Many Requests

Limite de uso do Free Tier por IP: quando esse limite é atingido, o retorno inclui um envelope JSON:

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "Identificamos muitas tentativas de acesso deste IP. Por favor, adquira um plano de assinatura para continuar a consultar."
  }
}

Repetir imediatamente a mesma chamada não resolve uma restrição de plano ou de limite de uso.

451 — restrição na consulta CPF

A integração online usa o SERPRO v3, que não retorna mais esse código por menoridade. O tratamento de HTTP 451 permanece por compatibilidade, caso a fonte ou uma resposta armazenada apresente essa restrição.

A restrição de menor de idade informada pelo SERPRO é devolvida com HTTP 451 nos dois layouts, sem cobrança. No SINTEGRAPI, o resultado contém success=false, error=true, cache=false e o código "451" em serpro_result e error_message. No layout SERPRO, code e message ficam na raiz.

{
  "code": "451",
  "message": "Consulta não permitida pelo SERPRO para este CPF (menor de idade)."
}

Esse retorno não consome créditos, mesmo quando identificado em uma resposta armazenada. Créditos reservados para a operação são devolvidos na finalização; contas pós-pagas registram custo zero. Veja os exemplos completos do CPF.

500 — falha não tratada

Quando uma exceção chega ao tratamento geral de erros, a resposta pública em produção é:

{
  "message": "Ocorreu um erro no servidor",
  "code": "500"
}

Não há request_id nem detalhes internos de exceção nesse corpo. Para o suporte, informe horário, rota, status e os identificadores disponíveis, sem enviar a chave de API.

503 — indisponibilidade temporária

Alguns fluxos retornam HTTP 503 quando a consulta não pode ser concluída. Exemplo de falha tratada na consulta Sintegra:

{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "success": false,
  "error": true,
  "error_message": {
    "message": "Ocorreu um erro ao consultar o CNPJ no Sintegra. Tente novamente em instantes."
  }
}

Essa falha não consome créditos. Aguarde antes de repetir e aumente gradualmente o intervalo se a indisponibilidade persistir. As CNDs também podem retornar HTTP 503 com envelope de erro quando o serviço está temporariamente indisponível.

No CPF, uma falha online sem cadastro utilizável nem fallback retorna HTTP 503 nos dois layouts, com custo zero. Veja os exemplos da consulta CPF. Nem toda indisponibilidade da API usa esse status: as CNDs também podem responder HTTP 400 com error=true e sem cobrança.

Outros retornos e diferenças entre consultas

HTTP 200 não garante a presença de dados utilizáveis. Confira os indicadores e os campos de negócio antes de atualizar seu cadastro. Na consulta CPF, por exemplo, verifique a presença de serpro_result.ni no layout SINTEGRAPI ou ni no layout SERPRO.

Uma situação cadastral ou fiscal desfavorável também não equivale a falha técnica. Uma empresa não optante pelo Simples Nacional ou uma certidão positiva pode ser um resultado válido para a integração. Interprete os campos específicos da consulta e consulte seus custos; não use apenas success ou o nome error_message para decidir se houve cobrança.

Tratamento na integração

1. Leia o status HTTP e confira se o corpo está vazio antes de tentar interpretá-lo como JSON.
2. Se houver JSON, procure mensagens em error_message.message, message ou nas listas de errors. Cada formato possui seu próprio conjunto de campos.
3. Mesmo com HTTP 200, confira os indicadores e os campos necessários ao cadastro. Um corpo vazio ou sem dados não comprova regularidade cadastral ou fiscal.
4. Corrija documento/parâmetros em erros de validação; revise chave, acesso ou saldo nos respectivos retornos; respeite os limites antes de tentar novamente. Para indisponibilidades, aumente o intervalo entre tentativas.
5. Em timeout ou perda de conexão, não conclua que a operação falhou sem cobrança: ela pode ter sido concluída antes de a resposta chegar. Na CND Federal, use a mesma chave de idempotência para a mesma operação.
6. Para suporte, guarde horário com fuso, método e rota, status, código/mensagem e request_id ou traceId, quando disponíveis. Informe esses dados sem enviar sua chave de API.