Homologação · Dados fictícios · Sem consumo de créditos

Erros simulados em homologação

O sandbox permite testar erros escolhendo um documento do catálogo. O código HTTP e o corpo seguem o contrato da consulta; não existe um formato único de erro. Nenhum cenário consome saldo, inclusive saldo insuficiente, acesso negado e timeout.

Selecionar uma falha

Abra o catálogo da consulta e busque por indisponivel, timeout, saldo-insuficiente, acesso-negado ou limite-requisicoes. Nem toda família possui todos os casos. Copie o documento e os parâmetros da mesma linha.

Os erros são determinísticos. Um timeout simulado retorna imediatamente, sem aguardar os segundos mencionados na mensagem. Quando o corpo inclui billing_status=consultar_historico, esse campo conserva o contrato da resposta; no sandbox não há histórico financeiro nem cobrança a reconciliar.

Códigos HTTP

HTTPComo exercitarInterpretação
200Ausências em Sintegra, Produtor Rural, CNPJ Receita Federal e Simples; falha técnica de Simples.Leia success, error e os campos da consulta.
207Cenário parcial do CNPJ multifonte, mantendo fontes com sucesso e com erro habilitadas.Confira cada fontes.*.status_http e dados.
400Documento ou parâmetro inválido; nascimento indisponível; cache federal ausente; algumas falhas de fonte.O corpo depende da validação ou da consulta.
401Omitir a chave ou enviar um valor diferente.Corpo vazio.
402Documento do cenário de saldo insuficiente.Falha simulada, sem vínculo com saldo real.
403Documento do cenário de acesso negado nas consultas que o oferecem.Mensagem na raiz ou envelope de erro.
404Documento válido sem resultado nas consultas aplicáveis; referência de comprovante inexistente.Ausência funcional ou erro específico, conforme a rota.
409Cenário de conflito de idempotência na CND Federal.Resposta simulada de requisição já processada.
429Documento do cenário de limite; ou limite real do sandbox atingido.Corpo vazio.
451Cenário de restrição na consulta CPF.Erro de consulta no layout solicitado.
503Cenários de indisponibilidade, timeout ou falha total no multifonte.Confira o corpo e os resultados individuais quando existirem.

Ausência de resultado

Um documento válido desconhecido recebe o cenário de ausência daquela consulta. Não considere todo HTTP 404 um erro técnico nem todo HTTP 200 um cadastro encontrado.

ConsultaRetorno de ausência
Sintegra e Produtor RuralHTTP 200, success=false, error=false e código interno "404".
Receita Federal CNPJHTTP 200, success=false e error=false.
Simples NacionalHTTP 200 e success=true; interprete os indicadores e períodos.
Suframa e Regimes TributáriosHTTP 404, success=false e error=false.
Receita Federal CPFHTTP 404 em SO_CACHE; em tentativa online sem nascimento disponível, HTTP 400. Com nascimento válido, ausência online HTTP 404.
CND EstadualHTTP 404, success=false e error=false.
CND FederalHTTP 404; com SO_CACHE, HTTP 400 e CACHE_NAO_ENCONTRADO.
CNPJ multifonteHTTP 200 quando todas as fontes selecionadas concluem, inclusive com ausência funcional.

A UF também pode remover todas as inscrições de um cenário Sintegra ou Produtor Rural, produzindo a resposta de ausência. No multifonte, uma fonte excluída não aparece na resposta e não participa da classificação do resultado parcial.

Formatos do corpo

FormatoOnde encontrar a informação
Envelope com request_id, success, error e error_messageLeia error_message.message e, quando existir, error_message.code.
Objeto com message e código opcionalLeia a mensagem diretamente na raiz.
Validação com title, status e errorsLeia as listas de mensagens em errors[nome_do_parametro].
CPF no layout SERPROErros da consulta podem apresentar code e message na raiz.
Sem corpoTrate pelo status HTTP; não tente interpretar JSON.

error_message.code pode ser uma string numérica ou um código próprio da consulta. Esse campo não substitui o status HTTP. Campos opcionais, nulos e listas vazias mantêm seus significados próprios.

Na consulta CPF, format=SERPRO transforma o resultado da consulta, mas não uniformiza erros gerais de autenticação, validação, acesso, saldo, limite ou timeout. Veja os parâmetros e layouts do CPF.

Validação antes dos cenários

A chave e os parâmetros são validados antes da seleção do documento. Por exemplo, uma UF inválida recebe HTTP 400 mesmo que o documento escolhido represente timeout. Um CNPJ ou CPF com dígitos inválidos recebe erro de entrada, em vez do cenário de ausência.

Na CND Federal, informe exatamente um documento e o nascimento quando usar CPF. O header Idempotency-Key deve conter entre 8 e 128 caracteres ASCII visíveis. A ausência no cache federal e o conflito simulado têm cenários próprios.

Use os exemplos da página de cada consulta para uma requisição válida inicial, depois altere uma entrada por vez. Abrir o catálogo completo.

Esta página foi útil?