Padrão de Erros - RFC 9457 (Problem Details for HTTP APIs)
Visão Geral
O PGCC-Service utiliza um formato padronizado para apresentar os erros que podem ocorrer durante uma requisição. Esse padrão facilita a identificação do problema e fornece informações mais claras sobre o motivo pelo qual uma operação não pôde ser concluída.
As respostas de erro seguem o padrão RFC 9457, garantindo que os diferentes erros do sistema sejam apresentados de maneira uniforme e previsível.
Estrutura da Resposta de Erro
Todas as respostas de erro seguem o formato application/problem+json:
{
"type": "about:blank",
"title": "Erro de Negócio",
"status": 400,
"detail": "Descrição detalhada do erro ocorrido",
"instance": "/pgcc/api/v1/endpoint-chamado",
"mnemonico": "CODIGO_DO_ERRO",
"timestamp": "2026-07-01T10:30:00.000Z"
}
Campos Padrão RFC 9457
| Campo | Tipo | Descrição |
|---|---|---|
type |
string | URI que identifica o tipo de problema (padrão: about:blank) |
title |
string | Resumo curto e legível do tipo de problema |
status |
integer | Código de status HTTP (ex: 400, 404, 500) |
detail |
string | Explicação específica sobre o erro ocorrido |
instance |
string | URI que identifica a ocorrência específica do problema |
Campos Customizados PGCC
| Campo | Tipo | Descrição |
|---|---|---|
code |
string | Código identificador único do erro no sistema (ex: VEICULO_NAO_ENCONTRADO) |
traceId |
string | Identificador único de rastreamento da requisição, gerado conforme o padrão W3C Trace Context e propagado por toda a cadeia de chamadas do PGCC. Para reportar um erro à equipe PGCC, o traceId deve ser informado. |
timestamp |
string | Data/hora ISO 8601 em que o erro ocorreu |
violacoes |
array | Lista de violações de validação (apenas para erros de validação) |
Catálogo de Erros (Codes)
O enum Erro define todos os códigos de erro disponíveis no sistema:
| Code | Descrição |
|---|---|
| VEICULO_NAO_ENCONTRADO | Veículo não encontrado |
| ERRO_RENAVAM | Falha reportada pelo próprio Renavam ao rejeitar a requisição de consulta |
| AUTORIZACAO_NAO_ENCONTRADA | Indica que o Credencia não localizou autorização de acesso válida para a combinação de credenciais apresentada na requisição |
| ERRO_METADADO_INVALIDO | Sinaliza que o template de tratamento recebido do Credencia não pôde ser aceito pelo PGCC por conter metadados incompletos, inconsistentes ou não reconhecidos |
| CONSENTIMENTO_PENDENTE | Indica que a consulta depende de consentimento do titular dos dados e que esse consentimento já foi solicitado, mas ainda não recebeu resposta |
| CONSENTIMENTO_NEGADO_PELO_TITULAR | Indica que o titular dos dados analisou o pedido de consentimento e o recusou expressamente |
| CONSENTIMENTO_REVOGADO | Indica que a consulta não pode ser realizada porque o consentimento do titular deixou de vigorar |
| CONSENTIMENTO_NAO_CRIADO | Indica que o pedido de consentimento não pôde ser registrado no Portal de Dados do Cidadão (PDC) |
| CONSENTIMENTO_NAO_ENCONTRADO | Indica que não existe registro de consentimento no PGCC para a combinação de parâmetros informada |
| TEMPLATE_NAO_ENCONTRADO | Indica que o template de tratamento informado na requisição não foi localizado na base do PGCC, ou que o contexto de tratamento associado a ele não existe para a combinação de entidades envolvidas |
| ERRO_DADOS_INCONSISTENTES | Indica que o PGCC detectou divergência entre dados que deveriam coincidir e interrompeu a operação por medida de integridade |
| ERRO_INTERNO | Indica falha não prevista no processamento da requisição pelo PGCC |
| ERRO_CREDENCIA | Indica que o Credencia rejeitou a solicitação enviada pelo PGCC por regras de validação do sistema de origem |
| ERRO_VALIDACAO_CERTIFICADO | Indica que o PGCC não conseguiu concluir a autorização do certificado digital apresentado na requisição |
| ERRO_INESPERADO | Indica falha não prevista durante a autorização do certificado digital, ocorrida fora do escopo da comunicação com o Credencia |
| ERRO_CPF_NAO_INFORMADO | Indica que a consulta exige consentimento do titular, mas o CPF desse titular não foi identificado na requisição |
| DATA_INVALIDA | Indica que uma das datas enviadas na operação de consentimento não pôde ser interpretada por não estar no formato esperado |
| ERRO_CONSULTA_CONDUTOR | Indica que a consulta de condutor não pôde ser executada porque nenhum identificador utilizável foi fornecido |
| ERRO_CONSULTA_FORMULARIO_RENACH | Indica que a consulta ao Renach pelo número do formulário Renach não pôde ser concluída |
| ERRO_CONSULTA_CNH_IMAGEM_BLOQUEIO | Indica que a consulta ao Renach para obtenção da imagem da CNH com registro de bloqueio não pôde ser concluída |
| ERRO_CONSULTA_DADOS_IDENTIFICATORIOS | Indica que a consulta ao Renach por dados identificatórios do condutor não pôde ser concluída |
| ERRO_CONSULTA_HISTORICO_CNH_CPF | Indica que a consulta ao histórico de Carteiras Nacionais de Habilitação vinculadas a um CPF não pôde ser concluída |
| ERRO_CONSULTA_CPF | Indica que a consulta de condutores vinculados a um CPF não pôde ser concluída |
| ERRO_CONSULTA_CPF_NUMERO_REGISTRO | Indica que a consulta de condutor pela combinação de número de registro e CPF não pôde ser concluída |
| ERRO_CONSULTA_CPF_NUMERO_REGISTRO_NUMERO_SEGURANCA | Indica que a consulta de condutor pela combinação de CPF, número de registro e número de segurança não pôde ser concluída |
| ERRO_CONSULTA_RETRATO_CPF | Indica que a consulta ao retrato do condutor a partir do CPF não pôde ser concluída |
| ERRO_CONSULTA_NUMERO_IMPEDIMENTO | Indica que a consulta de condutores por número de impedimento não pôde ser concluída |
| ERRO_CONSULTA_NUMERO_PGU | Indica que a consulta de condutores pelo número do PGU não pôde ser concluída |
| ERRO_CONSULTA_NUMERO_PID | Indica que a consulta de condutores pelo número do PID não pôde ser concluída |
| ERRO_CONSULTA_NUMERO_REGISTRO | Indica que a consulta de condutores pelo número de registro da CNH não pôde ser concluída |
| ERRO_CONSULTA_DIGITAIS_CPF | Indica falha técnica na consulta de condutor com dados biométricos digitais a partir do CPF |
| CONDUTOR_NAO_ENCONTRADO | Indica que não há condutor registrado para o CPF informado |
| ERRO_CONSULTA_INFRACOES_NUMERO_REGISTRO | Indica que a consulta de infrações associadas a um número de registro de CNH não pôde ser concluída |
| ERRO_FUNCIONALIDADE_NAO_IMPLEMENTADA | Indica que a funcionalidade solicitada não possui implementação no serviço |
| ERRO_FUNCIONALIDADE_NAO_HABILITADA | Indica que a funcionalidade existe, mas não está habilitada para o contexto da requisição |
| ERRO_PARAMETRO_INVALIDO | Indica que um parâmetro da requisição apresenta valor inadmissível |
| ERRO_PARAMETROS_ENTRADA | Indica que o conjunto de parâmetros da requisição não satisfaz as regras de validação aplicáveis |
| CNPJ_USUARIO_OBRIGATORIO | Indica que o cabeçalho x-cnpj-usuario não foi transmitido ou foi transmitido vazio |
| CNPJ_GCC_OBRIGATORIO | Indica que o cabeçalho x-cnpj-gcc não foi transmitido ou foi transmitido vazio |
| INFRACAO_NAO_ENCONTRADA | Indica que não foram localizadas infrações para os critérios informados |
| ERRO_HASH | Indica que o hash apresentado não pode ser utilizado |
| ERRO_DATA | Indica que uma data informada não pôde ser interpretada |
| GCC_NAO_ENCONTRADO | Indica que o CNPJ de Gestor de Consentimento do Cidadão não possui vínculo válido |
| ERRO_TEMPLATE | Indica incompatibilidade entre a operação solicitada e a configuração do template invocado |
| TEMPLATE_NAO_ENCONTRADA_CREDENCIA | Indica que o sistema Credencia não localizou registro ativo para a combinação de template e participantes informada |
| STATUS_CONSENTIMENTO_INVALIDO | Indica que a transição de status pretendida para o consentimento não é admitida |
| CERTIFICADO_NAO_ENCONTRADO | Indica que o certificado público necessário à verificação da assinatura não foi localizado |
| ERRO_ADMIN | Indica que o sistema Admin recusou a requisição de consulta de certificado por invalidade dos parâmetros |
| ERRO_AUTORIZADOR | Indica que o serviço de autorização recusou a requisição de token por invalidade dos parâmetros |
| ERRO_JWT | Indica que o JWT apresentado não pôde ser validado |
| ERRO_VALIDACAO_JWT | Indica que o hash correspondente ao JWT apresentado não foi localizado ou os CNPJs não conferem |
| ERRO_CRIAR_HASH | Indica que o hash não pôde ser constituído a partir do JWT apresentado |
| ERRO_VALIDACAO_DATAVALID | Indica que os parâmetros de entrada para a validação do DataValid não são admissíveis para o template informado |
Para a lista completa, consulte o enum
br.gov.serpro.denatran.pgcc.exception.Erro.