Codigos

o código do erro vem no campo 'code' do erro retornado

VEICULO_NAO_ENCONTRADO

Nenhum veículo foi localizado na base do Renavam para a combinação de parâmetros informada na consulta. O erro indica ausência de resultado, não falha de comunicação ou de autorização: a requisição foi processada com sucesso, o certificado e o template foram validados, mas o filtro aplicado não retornou registros.

Causas mais comuns:

Placa, chassi, Renavam, número do motor ou do câmbio inexistentes ou digitados incorretamente.
Combinação de parâmetros contraditória — por exemplo, placa e chassi que pertencem a veículos distintos. A busca é conjuntiva (todos os filtros informados precisam corresponder ao mesmo veículo).
O documento do proprietario informado não corresponde ao proprietário atual do veículo consultado.
Consulta com consentimento em que o titular não é o proprietário: o filtro adicional por possuidor restringe o resultado e pode eliminá-lo.
Veículo existente na base, mas fora do escopo de dados que o Renavam disponibiliza para a consulta realizada.

Como proceder

Confira os parâmetros enviados, especialmente caracteres facilmente confundíveis em placa e chassi (0/O, 1/I, 5/S, 8/B).
Prefira consultar por um único identificador (placa ou chassi ou Renavam) antes de combinar filtros.
Se estiver usando documento do proprietario, valide se o documento corresponde ao proprietário registrado.
Não repita a requisição automaticamente. O erro é determinístico — reenviar os mesmos parâmetros produzirá o mesmo resultado e consumirá uma nova cobrança/bilhetagem.
Persistindo a dúvida sobre um veículo que se sabe existir, acione o suporte informando o traceId da resposta.

Registro: a consulta é auditada e bilhetada mesmo sem retorno de dados, pois houve efetiva chamada ao Renavam.

ERRO_RENAVAM

Falha reportada pelo próprio Renavam ao rejeitar a requisição de consulta. Ocorre quando o serviço externo responde 400 Bad Request, indicando que os parâmetros enviados foram recebidos, mas considerados inválidos pelas regras de validação do sistema de origem — formato incorreto de placa, chassi ou Renavam, combinação de filtros não suportada, ou valores de paginação fora dos limites aceitos.

Diferentemente dos demais erros do catálogo, a mensagem deste código não é fixa: o campo detail reproduz literalmente o texto devolvido pelo Renavam (campo message do corpo da resposta), sem tradução ou reformulação. Por isso o conteúdo varia conforme a validação que falhou e deve ser lido como a explicação autoritativa da recusa.

Trata-se de um erro de entrada, não de indisponibilidade: a comunicação com o Renavam foi bem-sucedida e a resposta foi compreendida. Reenviar a mesma requisição sem corrigir os parâmetros produzirá idêntico resultado — o usuário deve ajustar os dados a partir da orientação contida em detail antes de tentar novamente. Indisponibilidades e falhas internas do Renavam (HTTP 5xx) não usam este código.

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. Ocorre quando a consulta de autorização — do certificado digital, da entidade ou do template — retorna sem correspondência, sinalizando que a entidade não está habilitada a executar a operação solicitada nos termos informados.

O erro é de habilitação, não de identidade: o certificado digital foi recebido e lido corretamente, mas o vínculo entre ele, o template de tratamento e o órgão/entidade credenciada não existe na base do Credencia, está inativo, ou não contempla o serviço requisitado. Difere de falhas de validação do certificado, que possuem código próprio.

Causas mais comuns:

entidade sem credenciamento concluído para o serviço no Credencia;
template informado não vinculado ao CNPJ do usuário;
anuente indicado sem relação de anuência ativa com o usuário; ou
vínculo/contrato encerrado ou suspenso após o credenciamento inicial.

Como proceder: o consumidor deve verificar, junto ao Credencia, se o credenciamento da entidade está ativo e se o template utilizado consta entre os autorizados para o certificado apresentado.

A repetição da requisição não altera o resultado — a regularização depende de ação administrativa no cadastro de credenciamento, e não de nova tentativa.

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. O erro pertence ao fluxo de sincronização de templates — acionado no processamento de eventos de credenciamento e na gravação dos metadados autorizados —, e não ao fluxo de consulta de dados pelo consumidor da API.

A mensagem é dinâmica e identifica precisamente o defeito encontrado, incluindo o idTemplateCredencia afetado e, quando aplicável, o campo problemático. As situações cobertas são:

Hipótese de tratamento ausente — a necessidade está sujeita à LGPD (naoAplicaLgpd não é verdadeiro), mas nenhuma finalidade foi informada. Sem base legal declarada, o template não pode ser registrado.
Rótulo obrigatório em branco — rotuloFinalidade ou rotuloCategoria vieram nulos ou vazios. Esses rótulos compõem o registro de tratamento enviado ao PDC e não admitem omissão.
Template sem metadados — nenhum grupo ou campo autorizado foi recebido. Um template sem metadados não delimita quais dados podem ser retornados e, portanto, não tem efeito prático.
Campo sem identificador PGCC — o campo veio sem idPgcc, impedindo o vínculo com o catálogo interno de campos.
Identificador desconhecido — o idPgcc informado não corresponde a nenhum campo cadastrado em campos_senatran. Indica campo novo ou descontinuado, ainda não refletido no catálogo do PGCC.

O erro é determinístico e não se resolve por nova tentativa: exige correção do cadastro do template no Credencia ou, no caso de identificador desconhecido, atualização do catálogo de campos do PGCC via migração. Enquanto persistir, o template não é registrado e as consultas que dele dependem falharão por template inexistente.

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. O pedido está registrado e aguarda a manifestação do titular no Portal de Dados do Cidadão (PDC) — não houve autorização nem recusa até o momento da requisição.

Trata-se de uma situação transitória e esperada no fluxo de acesso mediado por consentimento, não de uma falha. Todas as demais validações foram concluídas com sucesso: o certificado foi autorizado, o template é válido e o pedido de consentimento existe para o CPF e o template informados. O que impede a entrega dos dados é exclusivamente a ausência de decisão do titular.

Distinção dos demais estados: difere de CONSENTIMENTO_NAO_ENCONTRADO, em que nenhum pedido foi localizado para os parâmetros informados; de CONSENTIMENTO_NEGADO_PELO_TITULAR, em que houve recusa expressa; e de CONSENTIMENTO_REVOGADO, que abrange tanto a revogação posterior quanto a expiração do consentimento. Apenas o estado pendente admite mudança favorável sem nova solicitação.

Como proceder: o consumidor deve aguardar a manifestação do titular e repetir a consulta posteriormente — sem criar novo pedido de consentimento, o que geraria duplicidade. Não há prazo garantido de resposta, pois a decisão é ato voluntário do titular. Recomenda-se consultar com intervalos espaçados, em vez de tentativas sucessivas, e tratar este retorno como estado de espera na aplicação cliente, e não como erro a ser reportado ao usuário final.

CONSENTIMENTO_NEGADO_PELO_TITULAR

Indica que o titular dos dados analisou o pedido de consentimento e o recusou expressamente. A consulta não pode ser atendida porque falta a base legal que autorizaria o tratamento dos dados pessoais solicitados.

Diferentemente dos demais impedimentos, este não decorre de falha técnica, de erro nos parâmetros ou de pendência operacional: todas as validações anteriores foram concluídas com êxito — certificado autorizado, template válido e pedido de consentimento devidamente registrado para o CPF e o template informados. O acesso é barrado por decisão soberana do titular, no exercício do direito assegurado pela LGPD de recusar o tratamento de seus dados.

Caráter definitivo: a recusa encerra o ciclo daquele pedido. Nova tentativa de consulta com os mesmos parâmetros retornará sempre o mesmo resultado, pois a negativa permanece registrada como a última manifestação do titular. Não há reversão automática nem por decurso de prazo — apenas uma nova manifestação favorável do próprio titular, em pedido subsequente, alteraria o cenário.

Distinção dos estados correlatos: difere de CONSENTIMENTO_PENDENTE, em que ainda não houve decisão e a espera é legítima; e de CONSENTIMENTO_REVOGADO, em que houve autorização prévia posteriormente cancelada pelo titular ou expirada por decurso de validade. Em ambos os casos de recusa — negado e revogado — o efeito prático é idêntico: o acesso está vedado.

Como proceder: o consumidor deve cessar as tentativas para essa combinação de titular e template. Insistir na consulta não produzirá resultado diverso, gera cobrança indevida e configura desrespeito à manifestação do titular. A aplicação cliente deve registrar a negativa e interromper o fluxo, informando ao usuário final que o acesso depende de autorização não concedida. Reiterar o pedido de consentimento ao titular exige fundamento legítimo e não deve ser prática automatizada.

CONSENTIMENTO_REVOGADO

Indica que a consulta não pode ser realizada porque o consentimento do titular deixou de vigorar. O código expressa manifestação de vontade do cidadão: tendo autorizado o tratamento de seus dados em momento anterior, ele retirou essa autorização — direito que a Lei Geral de Proteção de Dados lhe assegura a qualquer tempo e mediante procedimento gratuito e facilitado (art. 18, IX, c/c art. 8º, § 5º).

O código abrange também o consentimento expirado. Embora as causas sejam distintas — num caso, ato do titular; no outro, decurso do prazo estipulado quando da coleta —, o efeito é o mesmo: não subsiste base legal que ampare o acesso.

Trata-se de recusa definitiva quanto ao consentimento em questão. Não há erro a corrigir na requisição, nem falha técnica a superar por nova tentativa: o acesso está vedado enquanto não houver nova manifestação do titular.

Como proceder: repetir a requisição não produzirá resultado diverso. A retomada do acesso depende da coleta de novo consentimento junto ao titular, por intermédio do Gestor de Consentimento do Cidadão responsável pelo caso de uso. Consentimento revogado é estado terminal e não comporta reativação — é necessário constituir consentimento novo. Cabe ao consumidor abster-se de novas tentativas sobre o mesmo titular e caso de uso, bem como observar, quanto aos dados já obtidos sob o consentimento revogado, as obrigações decorrentes da revogação.

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. Sem o template, o sistema não tem como determinar quais campos a entidade está autorizada a receber — o template é justamente o instrumento que delimita o escopo de dados de cada consulta.

O erro decorre de ausência de sincronização entre Credencia e PGCC, e não de invalidez do identificador em si. Templates são criados e mantidos no Credencia e replicados ao PGCC por eventos de credenciamento; enquanto essa replicação não ocorre, o identificador é desconhecido localmente ainda que válido na origem.

Situações cobertas:

Template inexistente localmente — o idTemplateCredencia informado não consta na base do PGCC, seja por evento de sincronização ainda não processado, seja por identificador incorreto.
Contexto de tratamento ausente — o template existe, mas não há contexto registrado para a combinação de template, CNPJ do usuário e CNPJ do anuente apresentada. Ocorre quando a entidade consulta em arranjo de anuência não previsto no credenciamento.
Template de tratamento não registrado no PDC — o contexto existe, porém sem identificador de template de tratamento no Portal de Dados do Cidadão, impedindo o registro do tratamento exigido pela LGPD.

Como proceder: o consumidor deve conferir se o idTemplateCredencia enviado corresponde ao template efetivamente credenciado e, no caso de acesso indireto, se o CNPJ do anuente informado integra o arranjo autorizado. Persistindo o erro para um template sabidamente ativo no Credencia, trata-se de pendência de sincronização, cuja regularização depende do processamento do evento de credenciamento no PGCC — nova tentativa imediata não produzirá efeito.

CONSENTIMENTO_NAO_CRIADO

Indica que o pedido de consentimento não pôde ser registrado no Portal de Dados do Cidadão (PDC). A chamada de criação foi enviada e respondida, mas o PDC não devolveu nenhum identificador de consentimento — sem esse identificador, o PGCC não tem como vincular o pedido ao titular e ao contexto de tratamento, nem como acompanhar posteriormente a manifestação do titular.

O erro interrompe o fluxo antes que qualquer consentimento passe a existir: não há pedido pendente aguardando decisão, e o titular não foi notificado. Trata-se, portanto, de falha na criação, e não de recusa ou de espera por resposta — estados que possuem códigos próprios e pressupõem um consentimento efetivamente registrado.

A causa está na integração com o PDC: resposta sem os identificadores esperados, rejeição silenciosa do pedido, ou inconsistência entre os dados enviados (template de tratamento, finalidades, categorias) e o que o PDC considera válido para registro. Não decorre de erro nos parâmetros informados pelo consumidor da API, que já foram validados nas etapas anteriores.

Como proceder: o consumidor deve tratar o retorno como falha temporária de integração e repetir a solicitação após algum intervalo. Persistindo o erro, o caso deve ser encaminhado ao suporte com o traceId da resposta, pois a regularização depende de análise conjunta entre PGCC e PDC — em especial da consistência do template de tratamento registrado. Como nenhum consentimento foi criado, a nova tentativa não gera risco de duplicidade.

CONSENTIMENTO_NAO_ENCONTRADO

Indica que não existe registro de consentimento no PGCC para a combinação de parâmetros informada. Nenhum pedido foi localizado para o titular no contexto de tratamento correspondente ao template, ao CNPJ do usuário e ao CNPJ do anuente apresentados.

O erro sinaliza ausência completa de registro — não há sequer pedido criado, muito menos manifestação do titular. Distingue-se dos demais estados do ciclo de consentimento, que pressupõem um consentimento existente: CONSENTIMENTO_PENDENTE indica pedido registrado à espera de decisão; CONSENTIMENTO_NEGADO_PELO_TITULAR e CONSENTIMENTO_REVOGADO, manifestações já ocorridas.

Situações cobertas:

Consentimento nunca solicitado — a entidade tentou consultar dados protegidos, ou verificar a situação do consentimento, sem antes ter criado o pedido para aquele titular e contexto.
Divergência no contexto de tratamento — existe consentimento para o titular, mas vinculado a outro contexto. Como a busca considera a combinação de template, usuário e anuente, alterar o arranjo de anuência aponta para um contexto distinto, no qual o consentimento não existe.
Identificador inexistente — a consulta direta por identificador de consentimento não encontrou o registro correspondente.

Como proceder: quando a consulta de dados depende de consentimento, o consumidor deve primeiro criar o pedido pelo endpoint de consentimento e aguardar a manifestação do titular. Se o pedido já foi criado anteriormente, convém verificar se os CNPJs de usuário e anuente enviados são exatamente os mesmos usados na criação — divergência nesses valores leva a outro contexto de tratamento e produz este erro ainda que o consentimento exista. Repetir a mesma requisição não altera o resultado.

ERRO_DADOS_INCONSISTENTES

Indica que o PGCC detectou divergência entre dados que deveriam coincidir e interrompeu a operação por medida de integridade. A verificação compara informações provenientes de fontes distintas — parâmetros da requisição, resposta de sistema externo e cadastro local — e recusa o resultado quando elas não se confirmam mutuamente.

A recusa é deliberada e protetiva: entregar dados que não correspondem ao que foi solicitado representaria risco de vazamento de informação de terceiro. Diante da divergência, o sistema prefere falhar a retornar conteúdo possivelmente indevido.

Situações cobertas:

Divergência entre filtro e retorno na consulta de condutor — o número de registro, o formulário Renach ou o número de segurança informados não correspondem aos valores presentes no registro devolvido pelo Renach.
Divergência entre filtro e retorno na consulta de infrações — placa, número Renainf ou CNH do infrator informados não conferem com os dados da infração devolvida pelo Renainf. A comparação normaliza formatos, considerando equivalência entre placa padrão e Mercosul e o preenchimento com zeros à esquerda do Renainf.
Empresa usuária divergente na resposta do Credencia — o CNPJ retornado pelo Credencia para o template não corresponde ao CNPJ informado na requisição.
Empresa ausente no cadastro local — o CNPJ exigido pela operação não consta na base de empresas do PGCC.
Template vinculado a outra empresa usuária — o template já está registrado para CNPJ distinto do informado, violando a regra de usuário único por template.

Como proceder: nas divergências entre filtro e retorno, o consumidor deve conferir se os identificadores combinados na consulta pertencem de fato ao mesmo registro — informar, por exemplo, um CPF e um número de registro de titulares diferentes produz este erro. Nos casos relativos a empresa e template, a inconsistência é cadastral e não se resolve pelo consumidor: exige regularização do credenciamento junto ao Credencia ou sincronização do cadastro no PGCC. Em nenhuma hipótese a repetição da requisição altera o resultado.

ERRO_INTERNO

Indica falha não prevista no processamento da requisição pelo PGCC. É o código genérico atribuído a situações que escapam ao tratamento específico dos demais erros do catálogo — exceções não capturadas, indisponibilidade de recursos internos e falhas de comunicação com sistemas externos que impedem a conclusão da consulta.

Diferentemente dos erros de negócio, não decorre de dado incorreto na requisição nem de restrição de autorização: a solicitação é legítima, mas o sistema não conseguiu processá-la. O consumidor não tem como corrigir a causa por conta própria.

Por se tratar de código genérico, a resposta não detalha a causa. Essa omissão é deliberada — expor mensagens internas de exceção revelaria detalhes de implementação e poderia vazar informação sensível. O diagnóstico fica registrado nos logs do servidor, correlacionáveis pelo traceId devolvido na resposta.

Como proceder: o consumidor deve tratar o erro como transitório e repetir a requisição após breve intervalo, preferencialmente com espaçamento progressivo entre tentativas. Persistindo a falha, o caso deve ser encaminhado ao suporte com o traceId, que permite localizar a ocorrência exata nos registros do servidor sem necessidade de reproduzir o cenário. Não há ajuste nos parâmetros que resolva a situação.

ERRO_CREDENCIA

Indica que o Credencia — sistema responsável pelo credenciamento de órgãos e entidades e pela autorização de acesso aos serviços — rejeitou a solicitação enviada pelo PGCC. A comunicação ocorreu normalmente, mas o pedido não foi aceito pelas regras de validação do sistema de origem.

A mensagem devolvida ao consumidor é dinâmica e repassa o texto produzido pelo próprio Credencia, precedido da identificação de origem. O conteúdo varia conforme a validação que falhou e constitui a explicação autoritativa da recusa — deve ser lido como orientação primária para a correção.

O erro ocorre nas etapas em que o PGCC consulta o Credencia para verificar se a entidade está habilitada: autorização do certificado digital apresentado e validação dos dados de credenciamento associados ao template. Situações típicas incluem certificado não vinculado ao template informado, combinação de CNPJs de usuário, anuente e GCC incompatível com o credenciamento registrado, ou parâmetros que não atendem às regras de validação do Credencia.

Como proceder: o consumidor deve analisar o texto retornado, que identifica o motivo específico da recusa, e verificar junto ao Credencia a situação do credenciamento da entidade e do template utilizado. Não se trata de indisponibilidade — repetir a requisição sem correção produzirá o mesmo resultado. Falhas de comunicação e indisponibilidade do Credencia resultam em códigos distintos.

ERRO_VALIDACAO_CERTIFICADO

Indica que o PGCC não conseguiu concluir a autorização do certificado digital apresentado na requisição. A etapa de validação junto ao Credencia — responsável por confirmar que o certificado está vinculado a uma entidade credenciada e habilitado para o template informado — falhou por motivo não atribuível aos dados enviados.

O erro decorre de falha na comunicação ou no processamento da autorização, e não de recusa fundamentada do certificado. Rejeições com motivo identificado pelo Credencia são reportadas sob código próprio, acompanhadas da explicação correspondente. Aqui, ao contrário, o sistema não obteve resposta conclusiva: indisponibilidade do Credencia, tempo de resposta excedido, erro interno no serviço de autorização ou falha inesperada no processamento.

A mensagem é deliberadamente genérica e orienta nova tentativa. Como a causa é técnica e externa ao consumidor, detalhar a falha não contribuiria para a correção — o diagnóstico fica registrado nos logs do servidor, associados ao traceId da resposta.

Como proceder: o consumidor deve tratar o erro como transitório e repetir a requisição após alguns instantes, preferencialmente com intervalos progressivos entre tentativas. Não há ajuste no certificado ou nos parâmetros que altere o resultado enquanto a causa persistir. Falhas recorrentes ao longo de período prolongado devem ser comunicadas ao suporte com o traceId, pois indicam indisponibilidade do serviço de autorização e não problema pontual.

ERRO_INESPERADO

Indica falha não prevista durante a autorização do certificado digital, ocorrida fora do escopo da comunicação com o Credencia. Distingue-se das demais falhas dessa etapa por não decorrer da resposta do serviço externo: a exceção surgiu no processamento interno do PGCC — ao preparar a requisição, ao interpretar o retorno ou em recurso de infraestrutura utilizado durante a operação.

Trata-se do último nível de tratamento da autorização de certificado. Rejeições fundamentadas pelo Credencia e falhas de comunicação com esse serviço possuem códigos próprios; este código cobre exclusivamente o que escapa a ambos.

A mensagem é genérica e orienta nova tentativa, sem detalhar a causa. A omissão é deliberada: expor a exceção interna revelaria detalhes de implementação sem oferecer ao consumidor qualquer elemento acionável. O diagnóstico permanece nos logs do servidor, localizáveis pelo traceId devolvido na resposta.

Como proceder: o consumidor deve tratar a falha como transitória e repetir a requisição após alguns instantes. Nenhum ajuste no certificado ou nos parâmetros altera o resultado. A recorrência do erro indica defeito que exige análise técnica — nesse caso, o suporte deve ser acionado com o traceId, que permite localizar a ocorrência exata sem necessidade de reproduzir o cenário.

ERRO_CPF_NAO_INFORMADO

Indica que a consulta exige consentimento do titular, mas o CPF desse titular não foi identificado na requisição. O template utilizado está marcado como dependente de consentimento e, sem o CPF, o PGCC não tem como localizar o consentimento aplicável nem verificar se o titular autorizou o tratamento dos dados solicitados.

O CPF não é enviado como parâmetro da consulta: ele é obtido do consentimento vinculado ao hash apresentado na requisição. O erro ocorre, portanto, quando o hash utilizado não possui consentimento associado — situação típica de hash gerado para acesso sem consentimento sendo empregado em consulta que o exige.

A validação é preliminar e protetiva: nenhuma chamada a sistema externo é realizada e nenhum dado pessoal é acessado. O PGCC interrompe o fluxo antes de qualquer tratamento, em observância ao princípio de que dados protegidos só podem ser acessados mediante base legal verificada.

Como proceder: o consumidor deve criar previamente o consentimento para o titular pelo serviço próprio e gerar o hash a partir desse consentimento, empregando-o na consulta. Convém verificar se o template informado é de fato o que exige consentimento e se o hash apresentado corresponde ao consentimento criado — reutilizar hash de outro contexto produz este erro. Repetir a requisição com o mesmo hash não altera o resultado.

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. A conversão falha antes de qualquer validação de conteúdo — o problema é sintático, não semântico: a data não foi reconhecida como tal, independentemente de o valor ser coerente.

A validação alcança três campos do fluxo de consentimento, com formatos distintos: - Data do pedido e data de expiração — devem seguir o formato de data simples aaaa-mm-dd. Ambas são interpretadas como o final do dia informado. - Data da resposta do titular — exige data com horário, no formato aaaa-mm-ddThh:mm:ss. O fuso considerado é o de Brasília (-03:00), que não deve ser incluído no valor enviado.

A causa mais frequente é o envio de data em formato diverso do esperado — notadamente o formato brasileiro dd/mm/aaaa —, o uso de data simples onde se exige data com horário, ou a inclusão de indicador de fuso horário no valor. Datas sintaticamente bem formadas mas inexistentes no calendário, como 31 de fevereiro, também são recusadas nesta etapa.

Como proceder: o consumidor deve conferir o formato de cada campo de data, observando que a data da resposta do titular difere das demais por exigir o horário. Trata-se de erro determinístico: a requisição só será aceita após a correção do valor, e repeti-la sem alteração produzirá o mesmo resultado.

ERRO_CONSULTA_CONDUTOR

Indica que a consulta de condutor não pôde ser executada porque nenhum identificador utilizável foi fornecido. A operação exige que o condutor seja identificado por ao menos um dentre CPF, número de registro da CNH ou número do formulário Renach — na ausência de todos, não há critério de busca a submeter ao Renach.

O CPF é o identificador efetivamente usado na consulta ao sistema de origem. Quando não é informado diretamente, o PGCC o obtém de forma automática a partir do número de registro ou do formulário Renach, em consulta preliminar. O erro ocorre quando nenhuma dessas três vias está disponível, tornando impossível resolver o CPF do condutor.

A validação é preliminar e ocorre antes de qualquer chamada externa: nenhum dado pessoal é acessado e nenhuma consulta é submetida ao Renach.

Como proceder: o consumidor deve incluir na requisição ao menos um dos três identificadores. Vale conferir se o campo pretendido foi de fato preenchido — valores vazios ou compostos apenas de espaços são tratados como ausentes. Como a falha é determinística, repetir a requisição sem incluir um identificador produzirá o mesmo resultado.

ERRO_CONSULTA_FORMULARIO_RENACH

Indica que a consulta ao Renach pelo número do formulário Renach não pôde ser concluída. A requisição foi submetida ao sistema de origem, mas a resposta obtida impediu o prosseguimento — seja por recusa do serviço, seja por falha de comunicação.

O erro alcança duas situações de naturezas distintas: número de formulário não localizado ou rejeitado pelo Renach, e indisponibilidade ou falha técnica do serviço.

A consulta pode ocorrer em dois momentos: como operação solicitada diretamente pelo consumidor, ou como etapa intermediária da consulta de condutor — quando o CPF não é informado, o PGCC o obtém previamente a partir do número do formulário. Nesse segundo caso, a falha interrompe a consulta principal antes que ela seja realizada.

Como proceder: o consumidor deve conferir o número do formulário Renach informado, atentando para dígitos omitidos ou transpostos. Confirmado o dado, a hipótese remanescente é de falha temporária do serviço — convém repetir a requisição após breve intervalo, com espaçamento progressivo entre tentativas. A recorrência do erro para um formulário sabidamente válido indica indisponibilidade do Renach e deve ser reportada ao suporte com o traceId.

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. A requisição foi submetida ao sistema de origem, mas a resposta obtida impediu o prosseguimento.

A operação é acionada pela funcionalidade de imagem de bloqueio e identifica o documento por CPF, número de registro da CNH ou número do formulário. Trata-se de consulta que retorna dado pessoal sensível — a imagem do documento —, razão pela qual o acesso depende de template que autorize expressamente esses campos.

O código abrange duas situações de naturezas distintas: documento não localizado ou identificadores rejeitados pelo Renach, e indisponibilidade ou falha técnica do serviço.

Como proceder: o consumidor deve conferir os identificadores informados, atentando para a correspondência entre eles — CPF e número de registro pertencentes a titulares distintos produzem falha. Confirmados os dados, a hipótese remanescente é de falha temporária do serviço, cabendo repetir a requisição após breve intervalo. A ausência de bloqueio registrado para o condutor também pode se manifestar por este código, situação em que nova tentativa não produzirá resultado diverso.

ERRO_CONSULTA_DADOS_IDENTIFICATORIOS

Indica que a consulta ao Renach por dados identificatórios do condutor não pôde ser concluída. A busca é feita pela combinação de nome do condutor, data de nascimento e nome da mãe, e a requisição submetida ao sistema de origem não retornou resultado utilizável.

Esta é a única modalidade de consulta de condutor que não emprega identificador único. Por basear-se em dados nominais, é sensível a variações de grafia: abreviações, nomes compostos, acentuação, partículas de ligação e a ordem dos sobrenomes precisam corresponder exatamente ao registrado na base do Renach. Pequenas divergências que passariam despercebidas a um leitor humano impedem a correspondência.

O código abrange duas situações distintas: condutor não localizado para a combinação informada — hipótese mais frequente, dada a sensibilidade à grafia — e indisponibilidade ou falha técnica do serviço.

Como proceder: o consumidor deve conferir a grafia dos nomes exatamente como constam no documento de identificação, sem abreviar, e verificar o formato da data de nascimento. Convém não omitir partículas como "de", "da" e "dos", nem substituir nomes compostos por iniciais. Confirmados os dados, a hipótese remanescente é de falha temporária do serviço, cabendo repetir a requisição após breve intervalo. Havendo identificador único disponível — CPF, número de registro ou formulário Renach —, é preferível utilizá-lo, por não estar sujeito a essa ambiguidade.

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. A requisição ao sistema de origem não retornou resultado utilizável.

Diferentemente das consultas que retornam o estado atual do condutor, esta recupera a sequência de habilitações já emitidas para o CPF informado — cada registro contendo o número do formulário, a data de emissão e a identificação da CNH anterior. Presta-se, portanto, a reconstituir a trajetória de habilitação da pessoa ao longo do tempo, e não apenas sua situação presente.

O código abrange, três situações: CPF sem qualquer habilitação registrada — condutor nunca habilitado ou cujos registros não constam da base consultada —, CPF inexistente ou inválido, e indisponibilidade ou falha técnica do serviço de origem.

Como proceder: o consumidor deve confirmar que o CPF está correto e foi transmitido apenas com os onze dígitos, sem pontos ou traço. Convém considerar também a possibilidade de que o titular simplesmente não possua histórico de habilitação, hipótese em que nenhuma repetição da consulta produzirá resultado diverso. Descartadas essas hipóteses, resta a falha temporária do serviço, cabendo repetir a requisição após breve intervalo.

ERRO_CONSULTA_CPF

Indica que a consulta de condutores vinculados a um CPF não pôde ser concluída. A requisição ao sistema de origem não retornou resultado utilizável.

Esta é a consulta mais abrangente entre as disponíveis para condutor: a partir do CPF, retorna a relação completa de registros de condutor associados ao titular, acompanhada da quantidade total encontrada. Como um mesmo CPF pode ter mais de um registro — em razão de transferências entre unidades da federação, renovações ou reemissões —, a resposta é paginada, e o campo idUltimoRegistro devolvido em cada página serve de marcador para solicitar a seguinte.

O código abrange, três situações: CPF sem nenhum registro de condutor associado, CPF inexistente ou malformado, e indisponibilidade ou falha técnica do serviço de origem.

Como proceder: o consumidor deve confirmar que o CPF está correto e foi transmitido apenas com os onze dígitos, sem pontos ou traço. Ao percorrer páginas, convém verificar que o idUltimoRegistro repassado corresponde exatamente ao valor recebido na página anterior, uma vez que marcador inválido também conduz a esta falha. Descartadas essas hipóteses, resta a indisponibilidade temporária do serviço, cabendo repetir a requisição após breve intervalo.

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. A requisição ao sistema de origem não retornou resultado utilizável.

Diferentemente da consulta apenas por CPF, que devolve todos os registros de condutor do titular, esta exige que ambos os identificadores sejam informados e correspondam entre si: o número de registro fornecido precisa pertencer ao CPF indicado. Presta-se, portanto, a confirmar um vínculo específico e a recuperar a versão resumida dos dados daquele registro, sem paginação.

O código abrange, três situações: ausência de registro que satisfaça simultaneamente os dois critérios — seja porque um deles está incorreto, seja porque pertencem a pessoas distintas —, identificadores malformados, e indisponibilidade ou falha técnica do serviço de origem.

Como proceder: o consumidor deve conferir que o CPF foi transmitido apenas com os onze dígitos e que o número de registro corresponde efetivamente ao titular daquele CPF. Havendo dúvida sobre qual registro pertence à pessoa, a consulta por CPF isolado permite obtê-lo previamente. Confirmados os dados, resta a indisponibilidade temporária do serviço, cabendo repetir a requisição após breve intervalo.

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. A requisição ao sistema de origem não retornou resultado utilizável.

Esta é a consulta de maior exigência probatória entre as disponíveis para condutor. O número de segurança é o código impresso no documento físico da CNH, destinado à verificação de autenticidade; exigi-lo, além do CPF e do número de registro, significa requerer evidência de que o solicitante teve o documento em mãos. Em contrapartida, é também a consulta de retorno mais amplo: devolve o conjunto completo de dados cadastrais do condutor — filiação, data e local de nascimento, nacionalidade, endereço residencial, categoria, datas de emissão e validade, unidade federativa de primeira habilitação e da habilitação atual.

Os três identificadores precisam corresponder ao mesmo registro. Basta que um deles divirja para que nenhum resultado seja produzido — não há correspondência parcial.

O código abrange, três situações: ausência de registro que satisfaça simultaneamente os três critérios, identificadores malformados, e indisponibilidade ou falha técnica do serviço de origem.

Como proceder: o consumidor deve conferir os três valores contra o documento de habilitação, atentando para que o número de segurança seja transcrito integralmente e sem separadores. Convém lembrar que o número de segurança é específico de cada via da CNH: após renovação ou emissão de segunda via, o código anterior deixa de ser válido. Confirmados os dados, resta a indisponibilidade temporária do serviço, cabendo repetir a requisição após breve intervalo.

ERRO_CONSULTA_RETRATO_CPF

Indica que a consulta ao retrato do condutor a partir do CPF não pôde ser concluída. A requisição ao sistema de origem não retornou resultado utilizável.

Esta consulta recupera a imagem facial constante do registro de habilitação do titular, acompanhada de seus dados cadastrais, da situação atual da CNH e da relação resumida de eventuais impedimentos. O retrato é dado biométrico — categoria que a Lei Geral de Proteção de Dados classifica como dado pessoal sensível (art. 5º, II) —, submetido, portanto, a regime de tratamento mais restritivo que os demais dados devolvidos pelo serviço.

O código abrange, três situações: ausência de retrato para o CPF informado — seja porque o titular não possui registro de habilitação, seja porque a imagem não consta da base —, CPF inexistente ou malformado, e indisponibilidade ou falha técnica do serviço de origem.

Como proceder: o consumidor deve confirmar que o CPF está correto e foi transmitido apenas com os onze dígitos. Convém considerar a hipótese de que o registro exista sem imagem associada, situação em que a repetição da consulta não produzirá resultado diverso. Descartadas essas hipóteses, resta a indisponibilidade temporária do serviço.

Cabe registrar que o acesso a esta funcionalidade pressupõe finalidade específica e consentimento válido do titular, dada a natureza sensível do dado. A imagem obtida não deve ser retida além do necessário ao propósito declarado.

ERRO_CONSULTA_NUMERO_IMPEDIMENTO

Indica que a consulta de condutores por número de impedimento não pôde ser concluída. A requisição ao sistema de origem não retornou resultado utilizável.

O impedimento é o registro de restrição que recai sobre a habilitação — suspensão, cassação, bloqueio administrativo ou judicial —, identificado por número próprio atribuído no momento de sua inscrição. Esta consulta parte desse número para recuperar o condutor a que a restrição se refere, retornando seu cadastro completo, a situação atual e anterior da CNH, as categorias autorizada e rebaixada, os motivos do requerimento e a relação de ocorrências de impedimento registradas.

É, portanto, consulta de sentido inverso às demais: em vez de partir da pessoa para conhecer sua situação, parte da restrição para identificar o condutor atingido. Destina-se sobretudo à instrução de procedimentos administrativos em que o número do impedimento já é conhecido.

O código abrange, três situações: inexistência de impedimento com o número informado, número malformado, e indisponibilidade ou falha técnica do serviço de origem.

Como proceder: o consumidor deve conferir o número do impedimento contra o documento ou processo de origem, atentando para que seja transcrito integralmente, com eventuais zeros à esquerda. Confirmado o dado, resta a indisponibilidade temporária do serviço, cabendo repetir a requisição após breve intervalo.

ERRO_CONSULTA_NUMERO_PGU

Indica que a consulta de condutores pelo número do PGU não pôde ser concluída. O PGU — Prontuário Geral Único — é o identificador nacional que consolida, sob um único número, os registros de habilitação de uma pessoa, ainda que emitidos por unidades federativas distintas ao longo do tempo. Presta-se, portanto, a reunir a trajetória completa do condutor, superando a fragmentação decorrente de transferências entre estados.

O código abrange, sem distingui-las na resposta, três situações: inexistência de prontuário com o número informado, número malformado, e indisponibilidade ou falha técnica do serviço de origem.

Como proceder: conferir o número do PGU contra a fonte de origem, atentando para zeros à esquerda. Confirmado o dado, repetir a requisição após breve intervalo.

ERRO_CONSULTA_NUMERO_PID

Indica que a consulta de condutores pelo número do PID não pôde ser concluída. O PID — Permissão Internacional para Dirigir — é o documento que habilita o condutor brasileiro a conduzir no exterior, emitido a partir de CNH válida e com prazo de validade próprio, distinto do da habilitação que lhe deu origem.

O código abrange, sem distingui-las, três situações: inexistência de PID com o número informado, número malformado, e indisponibilidade do serviço de origem.

Como proceder: conferir o número contra o documento, lembrando que o PID possui numeração própria, não coincidente com o número de registro da CNH. Confirmado o dado, repetir a requisição após breve intervalo.

ERRO_CONSULTA_NUMERO_REGISTRO

Indica que a consulta de condutores pelo número de registro da CNH não pôde ser concluída. O número de registro é o identificador da habilitação, impresso no documento e mantido ao longo das renovações dentro da mesma unidade federativa.

O código abrange, sem distingui-las, três situações: inexistência de registro com o número informado, número malformado, e indisponibilidade do serviço de origem.

Como proceder: conferir o número contra o documento de habilitação. Confirmado o dado, repetir a requisição após breve intervalo.

ERRO_CONSULTA_DIGITAIS_CPF

Indica falha técnica na consulta de condutor com dados biométricos digitais a partir do CPF. A consulta recupera as impressões digitais registradas no cadastro de habilitação — dado biométrico, classificado como dado pessoal sensível pela Lei Geral de Proteção de Dados (art. 5º, II).

Diferentemente das demais consultas desta família, este código não abrange a ausência de condutor: quando o titular não é localizado, o serviço devolve o código específico CONDUTOR_NAO_ENCONTRADO. Aqui, portanto, resta apenas a hipótese de falha ou indisponibilidade do serviço de origem.

Como proceder: repetir a requisição após breve intervalo. Persistindo a falha, acionar o suporte, informando o traceId da resposta.

O acesso a esta funcionalidade pressupõe finalidade específica e consentimento válido, dada a natureza biométrica do dado. As digitais obtidas não devem ser retidas além do necessário.

CONDUTOR_NAO_ENCONTRADO

Indica que não há condutor registrado para o CPF informado. Distingue-se dos códigos de falha técnica por afirmar um fato sobre a base consultada: o titular não possui registro de habilitação, ou o registro não consta do sistema de origem.

Como proceder: conferir que o CPF foi transmitido apenas com os onze dígitos. Confirmado o dado, a ausência de registro é a conclusão da consulta — repetir a requisição não produzirá resultado diverso.

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. A consulta admite recorte temporal por data inicial e final, retornando as autuações imputadas ao condutor no período.

O código abrange, sem distingui-las, três situações: ausência de infrações para o registro e período informados, parâmetros malformados, e indisponibilidade do serviço de origem.

Como proceder: conferir o número de registro e o formato das datas. Confirmados os dados, repetir a requisição após breve intervalo.

ERRO_FUNCIONALIDADE_NAO_IMPLEMENTADA

Indica que a funcionalidade solicitada não possui implementação no serviço. Trata-se de condição estrutural, não de problema com os dados da requisição: o identificador de funcionalidade é reconhecido, mas nenhuma operação está associada a ele.

Como proceder: repetir a requisição não produzirá resultado diverso. Consultar a documentação para verificar quais funcionalidades estão disponíveis na versão corrente do serviço.

ERRO_FUNCIONALIDADE_NAO_HABILITADA

Indica que a funcionalidade existe, mas não está habilitada para o contexto da requisição. A habilitação decorre da configuração do template: cada template define quais categorias de consulta — veículo, condutor, infração — estão autorizadas, e quais campos e parâmetros compõem cada uma. Ausentes esses metadados para a categoria solicitada, a consulta não pode ser processada.

Não se trata de falha técnica nem de erro nos dados enviados, mas de limite do que foi contratado e configurado para o template em uso.

Como proceder: repetir a requisição não produzirá resultado diverso. Verificar, junto ao gestor do template, se a categoria pretendida está prevista na configuração vigente.

ERRO_PARAMETRO_INVALIDO

Indica que um parâmetro da requisição apresenta valor inadmissível para o contexto em que foi empregado. A mensagem devolvida no campo detail descreve o parâmetro e a razão da recusa.

A hipótese mais frequente é a informação de CPF em consulta cujo template não exige consentimento: nesses casos, o CPF do titular não deve acompanhar a requisição, pois não há consentimento a que vinculá-lo. O código cobre ainda a ausência de parâmetros configurados para o template.

Como proceder: ler a mensagem devolvida, que identifica o parâmetro recusado, e ajustar a requisição. Repeti-la sem alteração não produzirá resultado diverso.

ERRO_PARAMETROS_ENTRADA

Indica que o conjunto de parâmetros da requisição não satisfaz as regras de validação aplicáveis. A mensagem devolvida no campo detail enumera os campos recusados e a razão de cada recusa.

Abrange três grupos de situações: campos obrigatórios ausentes ou com formato inválido, segundo a configuração de parâmetros do template; divergência entre o CPF informado na consulta e o CPF do titular vinculado ao consentimento; e ausência ou invalidade do número da página, nas consultas paginadas.

Como proceder: ler a mensagem devolvida, que discrimina os campos com problema, e ajustar a requisição. Nas consultas paginadas, atentar para que a página seja informada e seja igual ou superior a um.

CNPJ_USUARIO_OBRIGATORIO

Indica que o cabeçalho x-cnpj-usuario não foi transmitido na requisição, ou foi transmitido vazio. Esse cabeçalho identifica a pessoa jurídica usuária do dado — aquela que, no arranjo de credenciamento, figura como destinatária final da informação consultada e a quem se imputa a finalidade declarada do tratamento.

Sua exigência não é mera formalidade de protocolo: o CNPJ do usuário é elemento constitutivo do contexto de tratamento, confrontado com o conteúdo do hash e com os registros do Credencia ao longo de todo o fluxo de consulta. Sem ele, não há como aferir a legitimidade do acesso nem registrar corretamente a operação para fins de auditoria e prestação de contas.

O erro é apurado antes de qualquer processamento: nenhuma consulta é submetida ao sistema de origem, e nenhum dado pessoal é acessado.

Como proceder: incluir o cabeçalho x-cnpj-usuario na requisição, com o CNPJ da empresa usuária transmitido apenas em dígitos, sem pontos, barra ou traço. O valor deve corresponder ao CNPJ credenciado para o template invocado — divergência entre esse cabeçalho e o conteúdo do hash é apurada em etapa posterior e produz erro distinto.

CNPJ_GCC_OBRIGATORIO

Indica que o cabeçalho x-cnpj-gcc não foi transmitido na requisição, ou foi transmitido vazio. Esse cabeçalho identifica o Gestor de Consentimento do Cidadão — a pessoa jurídica que intermedeia a relação com o titular, responsável por coletar sua manifestação e por gerir o ciclo de vida do consentimento.

É exigido em todas as operações sobre consentimento e sobre hash, pois é a partir dele que se determina qual GCC responde pelo caso de uso invocado e se ela detém legitimidade para a operação pretendida.

O erro é apurado antes de qualquer processamento; nenhum dado pessoal é acessado.

Como proceder: incluir o cabeçalho x-cnpj-gcc na requisição, com o CNPJ transmitido apenas em dígitos, sem pontos, barra ou traço. O valor deve corresponder a GCC vinculada ao template invocado — a inexistência da GCC ou a ausência de vínculo é apurada em etapa posterior e produz o código GCC_NAO_ENCONTRADO.

INFRACAO_NAO_ENCONTRADA

Indica que não foram localizadas infrações para os critérios informados. Distingue-se dos códigos de falha técnica por afirmar um fato sobre a base consultada: no período e para os identificadores fornecidos, nenhuma autuação consta do Renainf.

Como proceder: conferir os identificadores — placa, número do Renainf, CNH do infrator — e o intervalo de datas. Confirmados os dados, a ausência de infrações é a conclusão da consulta.

ERRO_HASH

Indica que o hash apresentado não pode ser utilizado. O hash é o identificador que representa, no PGCC, uma autorização de consulta previamente constituída a partir de JWT válido: carrega o template, os CNPJs envolvidos, o vínculo com o consentimento e o prazo de validade.

O código abrange duas famílias de situações. Na constituição do hash, recusas de conteúdo do payload: campos obrigatórios ausentes, datas fora do formato ISO-8601, data de expiração anterior à de criação, ou indicação de consentimento sem o respectivo identificador. No uso do hash, recusas de estado: hash já consumido, excluído, expirado, ou desprovido do consentimento que o template exige.

A mensagem devolvida no campo detail especifica qual condição foi violada.

Como proceder: tratando-se de recusa de conteúdo, corrigir o payload do JWT e reapresentá-lo. Tratando-se de recusa de estado, obter novo hash — o hash é de uso único e prazo determinado, não sendo possível reaproveitá-lo após o consumo ou o vencimento.

ERRO_DATA

Indica que uma data informada não pôde ser interpretada. Abrange a omissão do campo e o emprego de formato não reconhecido — esperando-se o padrão ISO-8601 de data e hora, na forma 2024-06-30T12:34:56.

A mensagem devolvida no campo detail distingue as duas hipóteses e, no caso de formato inválido, reproduz o valor recusado.

Como proceder: ajustar a data ao formato ISO-8601, atentando para a presença do separador T entre data e hora.

GCC_NAO_ENCONTRADO

Indica que o CNPJ de Gestor de Consentimento do Cidadão apresentado na requisição não possui vínculo válido com o contexto pretendido. Abrange três situações: o CNPJ não corresponde a nenhuma GCC cadastrada; a GCC existe, mas não está vinculada a nenhum template; ou está vinculada a outros templates, mas não ao que a requisição invoca.

Nas operações sobre consentimento já constituído, o código expressa recusa de acesso: a GCC solicitante não é a que responde pelo caso de uso daquele consentimento, e portanto não detém legitimidade para alterá-lo.

A mensagem devolvida reproduz o CNPJ recusado.

Como proceder: conferir o CNPJ transmitido no cabeçalho x-cnpj-gcc. Estando correto, verificar junto ao gestor do template se o vínculo entre a GCC e o template foi efetivado.

ERRO_TEMPLATE

Indica incompatibilidade entre a operação solicitada e a configuração do template invocado. Ocorre quando se pretende constituir consentimento sobre template que não o exige: a configuração declara que a consulta prescinde de consentimento do titular, de modo que não há o que consentir.

A mensagem devolvida identifica o template.

Como proceder: verificar se o template informado é o pretendido. Sendo o caso de consulta sem consentimento, a operação de constituição deve ser simplesmente omitida — o acesso se dá diretamente, sem essa etapa.

TEMPLATE_NAO_ENCONTRADA_CREDENCIA

Indica que o sistema Credencia não localizou registro ativo para a combinação de template e participantes informada. A consulta ao Credencia verifica, a um só tempo, a existência do template e a situação de credenciamento das pessoas jurídicas envolvidas — usuário, anuente e GCC.

O código abrange, portanto, tanto a inexistência do template quanto a ausência de credenciamento ativo de algum dos participantes para aquele template.

Como proceder: conferir o identificador do template e os CNPJs transmitidos. Confirmados os dados, verificar junto ao Credencia se o credenciamento das partes está ativo — credenciamento suspenso ou encerrado produz o mesmo resultado que template inexistente.

STATUS_CONSENTIMENTO_INVALIDO

Indica que a transição de status pretendida para o consentimento não é admitida. O consentimento observa máquina de estados com transições predefinidas: de pendente, pode passar a ativo ou negado; de ativo, a revogado; de negado, de volta a ativo. O estado revogado é terminal — consentimento revogado não comporta alteração posterior.

O código cobre ainda a solicitação de status fora do conjunto admitido para atualização, restrito a ATIVO, REVOGADO e NEGADO.

A mensagem devolvida descreve a transição recusada e indica os destinos admissíveis a partir do estado corrente.

Como proceder: consultar o status atual do consentimento antes de solicitar a alteração e verificar se a transição pretendida é admitida. Para consentimento revogado, nova manifestação do titular exige a constituição de novo consentimento.

CERTIFICADO_NAO_ENCONTRADO

Indica que o certificado público necessário à verificação da assinatura não foi localizado no sistema Admin. Cada GCC registra, no Admin, as chaves públicas correspondentes às chaves privadas com que assina seus JWT; a chave a empregar é indicada pelo campo kid do cabeçalho do token.

Como proceder: verificar se o kid do JWT corresponde a chave efetivamente cadastrada no Admin para a GCC. Rotação de chaves sem o correspondente registro no Admin é a causa típica desta falha.

ERRO_ADMIN

Indica que o sistema Admin recusou a requisição de consulta de certificado por invalidade dos parâmetros. A mensagem devolvida reproduz a descrição fornecida pelo próprio Admin.

Como proceder: ler a mensagem devolvida, originária do sistema Admin, e ajustar os parâmetros. Persistindo a recusa, acionar o suporte informando o traceId.

ERRO_AUTORIZADOR

Indica que o serviço de autorização recusou a requisição de token por invalidade dos parâmetros. A mensagem devolvida reproduz a descrição fornecida pelo próprio serviço.

Como proceder: ler a mensagem devolvida e ajustar as credenciais ou parâmetros de autorização. Persistindo a recusa, acionar o suporte informando o traceId.

ERRO_JWT

Indica que o JWT apresentado não pôde ser validado. O token é a forma pela qual a GCC comprova, perante o PGCC, a legitimidade da consulta pretendida; sua validação percorre a estrutura do token, a localização da chave pública correspondente e a verificação da assinatura.

O código abrange quatro famílias de situações: estrutura — token que não se decompõe nas três partes esperadas; cabeçalho incompleto — ausência dos campos obrigatórios alg, que declara o algoritmo de assinatura, ou kid, que identifica a chave; chave indisponível — nenhuma chave pública cadastrada no Admin para o kid indicado; e algoritmo não suportado — declaração de algoritmo fora das famílias HMAC, RSA e curvas elípticas.

Cobre ainda a recusa do Credencia na autorização da pessoa jurídica para o template informado.

A mensagem devolvida especifica qual condição foi violada.

Como proceder: conferir a integridade do token transmitido, atentando para truncamento ou inclusão indevida de aspas. Verificar que o kid corresponde a chave cadastrada no Admin e que o algoritmo declarado é suportado. Persistindo a recusa na etapa de autorização, verificar o credenciamento das empresas junto ao Credencia.

ERRO_VALIDACAO_JWT

Indica que o hash correspondente ao JWT apresentado não foi localizado, ou que os CNPJs informados na requisição não conferem com os registrados no hash.

O código abrange três situações. Hash inexistente: o JWT não corresponde a nenhum hash registrado — o token pode já ter sido consumido, ter expirado, ou não ter sido previamente cadastrado pela GCC no PGCC, etapa indispensável ao seu uso. Divergência de CNPJ: o CNPJ de usuário ou de anuente transmitido na requisição não coincide com o gravado no hash. Coincidência indevida: o CNPJ do anuente é idêntico ao do usuário, o que a modelagem não admite, por pressupor partes distintas.

Cobre ainda a divergência entre o CPF do titular informado e o validado em etapa anterior do mesmo fluxo.

Como proceder: confirmar que o JWT foi previamente cadastrado no PGCC e que ainda não foi consumido — o hash é de uso único. Conferir os CNPJs transmitidos nos cabeçalhos contra os declarados no payload do token. Sendo caso de divergência de CPF, verificar que o titular é o mesmo ao longo de todo o fluxo.

ERRO_CRIAR_HASH

Indica que o hash não pôde ser constituído a partir do JWT apresentado. A criação do hash é a etapa em que a GCC registra no PGCC a autorização que utilizará nas consultas subsequentes; exige token válido e coerência entre o seu conteúdo e os registros do sistema.

O código abrange quatro famílias de situações. Token inválido: a validação do JWT falhou, e a mensagem reproduz a razão apurada. Divergência de CNPJ: o CNPJ da GCC declarado no token não coincide com o transmitido no cabeçalho da requisição. Contexto inexistente: a combinação de template e CNPJs — GCC, usuário e anuente — não corresponde a contexto de tratamento cadastrado. Incoerência de consentimento: o template exige consentimento e o token declara não possuí-lo; ou declara possuí-lo sem informar o identificador; ou o consentimento indicado não existe, pertence a outro template, ou tem empresa anuente diversa da declarada.

A mensagem devolvida especifica qual condição foi violada.

Como proceder: conferir que o CNPJ da GCC no cabeçalho coincide com o do token. Verificar que o contexto de tratamento — template e as três empresas — está devidamente cadastrado. Exigindo o template consentimento, assegurar que o token o declare e informe o identificador de consentimento correspondente ao mesmo template e à mesma anuente.

ERRO_VALIDACAO_DATAVALID

Indica que os parâmetros de entrada destinados à validação junto ao DataValid não são admissíveis para o template informado. O DataValid é o serviço de verificação de identidade do cidadão; a consulta que o emprega declara quais atributos serão confrontados, e esses atributos precisam estar previstos na configuração do template.

O código abrange duas situações: lista de parâmetros vazia, e presença de parâmetros não contemplados pelo template. Na segunda hipótese, a mensagem devolvida enumera os parâmetros recusados.

Como proceder: informar ao menos um parâmetro de validação e verificar, na configuração do template, quais atributos estão habilitados para confronto. Parâmetro não previsto não pode ser incluído, ainda que reconhecido pelo DataValid.

ERRO_VALIDACAO_JWT

Hash (Token JWT) não encontrado na base de dados do PGCC para o JWT informado na requisição. Possivelmente já foi consumido, ou a validade do token expirou ou a GCC não cadastrou o token no PGCC. Verifique se o JWT informado é válido e se a GCC cadastrou o token no PGCC.