Status e erros

A API idCerberus separa o status HTTP do status técnico retornado no body. Em integrações, leia os dois.

Estrutura padrão

{
  "result": {},
  "status": {
    "code": 200,
    "message": "Success"
  },
  "externalId": "8e1ac243-4510-4ebf-ac7d-4b6d133dd619"
}

Campo	Uso
`result`	Dados retornados pelo produto consultado
`status.code`	Código técnico do processamento
`status.message`	Mensagem técnica do processamento
`externalId`	Identificador externo da consulta, quando retornado

Como interpretar

Caso	Significado prático	Ação recomendada
HTTP 200 e `status.code` 200	A chamada foi processada	Ler `result` e seguir a regra de negócio
HTTP 200 e `status.code` 400	A API respondeu, mas o processamento falhou	Ler `status.message`, validar parâmetros e permissão
HTTP 401 ou 403	Problema de autenticação ou permissão	Gerar novo token ou revisar credenciais/produto liberado
Timeout	Fonte externa ou rede pode ter demorado	Aplicar retry controlado, sem loop agressivo
Sem body JSON	O endpoint retorna outro tipo de conteúdo	Tratar conforme contrato, como PDF no relatório de onboarding

Problemas comuns

Problema	Possível causa	Como resolver
Token inválido	Token gerado com credenciais erradas ou ambiente incorreto	Gere um novo token no mesmo ambiente da chamada
Token expirado	O tempo de validade do token acabou	Gere um novo token e repita a chamada
`Authorization` ausente	Header não foi enviado	Envie `Authorization: Bearer {jwt_token}`
`Content-Type` ausente	Body JSON enviado sem header correto	Envie `Content-Type: application/json`
Campo `service` ausente	Payload não informou qual produto executar	Inclua o campo `service` no body
CPF ou CNPJ inválido	Documento incompleto, mascarado ou fora do padrão esperado	Revise o valor enviado antes de chamar a API
Serviço sem permissão	Produto não liberado para a conta	Confirme a liberação do serviço com o time responsável
Fonte externa indisponível	Consulta depende de órgão, base ou processamento externo	Faça retry controlado ou tente novamente depois
URL de ambiente errada	Token de HML usado em produção, ou o contrário	Confira se a URL base e o token são do mesmo ambiente

Exemplos de erro

Token ausente ou inválido

Quando o header Authorization não é enviado, está expirado ou pertence a outro ambiente, a API pode retornar erro de autenticação.

HTTP/1.1 401 Unauthorized

Como corrigir:

Gere um novo token em POST /api/token-generate.
Confirme se o token foi gerado no mesmo ambiente da chamada.
Envie o header no formato abaixo.

Authorization: Bearer {jwt_token}

Campo `service` ausente

O endpoint POST /api/service-api precisa do campo service para saber qual produto executar. Payload incorreto:

{
  "cpf": "cpf"
}

Payload correto:

{
  "service": "SERVICE_PERSON_DATA_ENRICHMENT",
  "cpf": "cpf"
}

Documento obrigatório ausente

Se o serviço exige cpf, cnpj, imagem ou outro campo obrigatório, envie o campo correspondente no body. Exemplo de retorno:

{
  "result": {},
  "status": {
    "code": 400,
    "message": "CPF não encontrado."
  }
}

Como corrigir:

{
  "service": "SERVICE_RFB_PF",
  "cpf": "cpf"
}

Produto sem permissão ou não habilitado

Se a credencial não tiver acesso ao produto, a chamada pode falhar mesmo com token válido.

{
  "result": {},
  "status": {
    "code": 400,
    "message": "Serviço não disponível para este cliente."
  }
}

Como corrigir:

confirme se o service está escrito exatamente como na documentação;
valide se o produto está liberado para a conta;
confirme se está chamando o ambiente correto.

Fonte externa indisponível

Algumas consultas dependem de bases externas. Quando a fonte falha ou demora, a API pode retornar erro técnico.

{
  "result": {},
  "status": {
    "code": 500,
    "message": "Failed to fetch information"
  }
}

Como tratar:

registre o externalId, quando existir;
tente novamente depois com retry limitado;
não faça loop infinito de chamadas;
se o erro persistir, encaminhe o payload e o horário da tentativa para suporte.

Negativo não é erro técnico

Alguns serviços retornam uma consulta negativa como sucesso técnico. Exemplos:

Resultado	Exemplo
Nada consta	Certidões criminais ou ações judiciais
Cliente não encontrado	Validação de CPF com endereço
Sem débitos	Débitos ativos com totais zerados
Não PEP	Pessoa politicamente não exposta

Nesses casos, a chamada pode ter status.code 200 e ainda assim representar uma resposta negativa de negócio.

Boas práticas de tratamento

Registre o externalId quando ele vier no retorno.
Não use apenas HTTP status para decidir sucesso de negócio.
Trate token expirado gerando novo token.
Valide campos obrigatórios antes de chamar a API.
Evite retry automático em erro de payload.
Use retry com limite para timeout ou falha temporária de fonte externa.

Exemplo de decisão

if (response.status?.code !== 200) {
    throw new Error(response.status?.message || "Falha no processamento");
}

return response.result;

Primeiros passos

Suporte e referência

Fluxos principais

POST /api/service-api

Pessoas

Empresas

Catálogo técnico

Status e erros

Status e erros

Estrutura padrão

Como interpretar

Problemas comuns

Exemplos de erro

Token ausente ou inválido

Campo `service` ausente

Documento obrigatório ausente

Produto sem permissão ou não habilitado

Fonte externa indisponível

Negativo não é erro técnico

Boas práticas de tratamento

Exemplo de decisão

​Status e erros

​Estrutura padrão

​Como interpretar

​Problemas comuns

​Exemplos de erro

​Token ausente ou inválido

​Campo service ausente

​Documento obrigatório ausente

​Produto sem permissão ou não habilitado

​Fonte externa indisponível

​Negativo não é erro técnico

​Boas práticas de tratamento

​Exemplo de decisão

Status e erros

Estrutura padrão

Como interpretar

Problemas comuns

Exemplos de erro

Token ausente ou inválido

Campo `service` ausente

Documento obrigatório ausente

Produto sem permissão ou não habilitado

Fonte externa indisponível

Negativo não é erro técnico

Boas práticas de tratamento

Exemplo de decisão