Pular para conteúdo

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

  1. Confira os parâmetros enviados, especialmente caracteres facilmente confundíveis em placa e chassi (0/O, 1/I, 5/S, 8/B).
  2. Prefira consultar por um único identificador (placa ou chassi ou Renavam) antes de combinar filtros.
  3. Se estiver usando documento do proprietario, valide se o documento corresponde ao proprietário registrado.
  4. 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.
  5. 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 de acordo com o erro identificado e deve ser considerado como o motivo da recusa informado pelo Renavam.

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.

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:

  • 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.

ERRO_TEMPLATE_INVALIDO

Sinaliza que o template de tratamento recebido do Credencia não pôde ser aceito pelo PGCC porque contém informações obrigatórias ausentes ou inválidas. O erro ocorre durante o processamento de eventos de credenciamento, na validação da necessidade de tratamento e na preparação dos dados do template para registro no PDC. Não está relacionado ao fluxo de consulta de dados pelo consumidor da API.

A mensagem é dinâmica e identifica o idTemplateCredencia afetado e, quando aplicável, o campo obrigatório que apresentou problema. As situações cobertas são:

  • Hipótese de tratamento ausente — a necessidade está sujeita à LGPD (naoAplicaLgpd diferente de true), mas não possui nenhuma finalidade informada. Sem a finalidade que fundamenta o tratamento, o template não pode ser registrado.
  • Rótulo de finalidade ausente — rotuloFinalidade não foi informado ou está vazio. Esse valor é utilizado na identificação da finalidade do tratamento enviado ao PDC.
  • Rótulo de categoria ausente — o nome da necessidade, utilizado como rotuloCategoria, não foi informado ou está vazio. Esse valor é obrigatório para a identificação da categoria do tratamento.

O erro é determinístico e não é resolvido por uma nova tentativa. É necessário corrigir o cadastro do template ou da necessidade no Credencia, preenchendo as finalidades e os rótulos obrigatórios. Enquanto a inconsistência persistir, o contexto de tratamento não será registrado no PGCC/PDC, e as consultas que dependerem desse template poderão falhar por ausência do tratamento correspondente.

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.

Situações cobertas:

  • 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.
  • 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.

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.

SERVICO_INDISPONIVEL

Este erro indica que não foi possível concluir a consulta por uma falha de infraestrutura em um serviço externo (integradores RENACH, RENAVAM ou RENAINF) ou numa etapa interna anterior à chamada. É uma condição temporária e não cobrável — ou seja, a consulta não é debitada (o hash não é consumido).

Por segurança, o serviço não expõe o detalhe técnico nem o status original do integrador. Esses dados ficam registrados apenas internamente e podem ser recuperados pelo suporte por meio do traceId presente na resposta.

Como proceder: Aguarde e tente novamente após alguns instantes — a falha costuma ser transitória. Recomenda-se repetir a chamada com um intervalo (ex.: backoff progressivo), evitando repetições imediatas em sequência.

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

Sinaliza que uma data ou data/hora recebida pelo PGCC não pôde ser convertida para o formato esperado. O erro ocorre nos fluxos de consentimento, durante o processamento da data do pedido, da data de expiração e da data/hora da resposta do titular, além de ser utilizado pelo utilitário geral de conversão de datas. As situações cobertas são:

  • Data não informada — o valor é nulo ou vazio.
  • Formato de data inválido — a data não segue o padrão yyyy-MM-dd, utilizado para o pedido e a expiração do consentimento.
  • Formato de data/hora inválido — a data/hora não segue o padrão yyyy-MM-dd'T'HH:mm:ss, utilizado na resposta do titular.
  • Data inexistente — os valores contêm componentes inválidos, como mês, dia ou horário fora dos limites permitidos.

A mensagem é dinâmica e informa o valor recebido ou a causa identificada, como “data não informada” ou “Formato de data inválido”. O erro é determinístico e não se resolve por nova tentativa: é necessário corrigir o valor enviado na requisição para que o processamento possa prosseguir.

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_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_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.

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.