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
| HTTP | Como exercitar | Interpretação |
|---|---|---|
| 200 | Ausências em Sintegra, Produtor Rural, CNPJ Receita Federal e Simples; falha técnica de Simples. | Leia success, error e os campos da consulta. |
| 207 | Cenário parcial do CNPJ multifonte, mantendo fontes com sucesso e com erro habilitadas. | Confira cada fontes.*.status_http e dados. |
| 400 | Documento ou parâmetro inválido; nascimento indisponível; cache federal ausente; algumas falhas de fonte. | O corpo depende da validação ou da consulta. |
| 401 | Omitir a chave ou enviar um valor diferente. | Corpo vazio. |
| 402 | Documento do cenário de saldo insuficiente. | Falha simulada, sem vínculo com saldo real. |
| 403 | Documento do cenário de acesso negado nas consultas que o oferecem. | Mensagem na raiz ou envelope de erro. |
| 404 | Documento válido sem resultado nas consultas aplicáveis; referência de comprovante inexistente. | Ausência funcional ou erro específico, conforme a rota. |
| 409 | Cenário de conflito de idempotência na CND Federal. | Resposta simulada de requisição já processada. |
| 429 | Documento do cenário de limite; ou limite real do sandbox atingido. | Corpo vazio. |
| 451 | Cenário de restrição na consulta CPF. | Erro de consulta no layout solicitado. |
| 503 | Cená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.
| Consulta | Retorno de ausência |
|---|---|
| Sintegra e Produtor Rural | HTTP 200, success=false, error=false e código interno "404". |
| Receita Federal CNPJ | HTTP 200, success=false e error=false. |
| Simples Nacional | HTTP 200 e success=true; interprete os indicadores e períodos. |
| Suframa e Regimes Tributários | HTTP 404, success=false e error=false. |
| Receita Federal CPF | HTTP 404 em SO_CACHE; em tentativa online sem nascimento disponível, HTTP 400. Com nascimento válido, ausência online HTTP 404. |
| CND Estadual | HTTP 404, success=false e error=false. |
| CND Federal | HTTP 404; com SO_CACHE, HTTP 400 e CACHE_NAO_ENCONTRADO. |
| CNPJ multifonte | HTTP 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
| Formato | Onde encontrar a informação |
|---|---|
Envelope com request_id, success, error e error_message | Leia error_message.message e, quando existir, error_message.code. |
Objeto com message e código opcional | Leia a mensagem diretamente na raiz. |
Validação com title, status e errors | Leia as listas de mensagens em errors[nome_do_parametro]. |
| CPF no layout SERPRO | Erros da consulta podem apresentar code e message na raiz. |
| Sem corpo | Trate 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.
