Tratamento de erros

Todos os endpoints constroem a resposta HTTP pelo mesmo mecanismo, o que garante o mesmo formato de erro em toda a API.

Envelope de erro

Quando a requisição falha por regra de negócio ou por exceção não tratada, o corpo é um ResponseListMessage:

{
  "messages": [
    { "code": "4051004", "text": "Termo de autorização não está ativo ou expirou" },
    { "code": "4051007", "text": "Informe o vínculo empregatício a consultar" }
  ]
}

Trate o erro pelo code, que é estável, e não pelo text, que pode mudar.

Status HTTP e quando ocorrem

Status	Quando ocorre	Corpo
200 OK	GET bem-sucedido; PUT que retorna o recurso atualizado (assinatura, desembolso, averbação); sincronização da assinatura (POST .../signature-requests/current/sync).	Objeto do recurso
201 Created	POST bem-sucedido. Vale também para as consultas persistidas (vínculos, dados do trabalhador, FGTS, simulação), pois cada chamada grava um registro histórico, e para os pedidos processados em segundo plano (signature-requests), que devolvem o pedido e não o resultado final.	Objeto criado
400 Bad Request	Qualquer erro de validação ou de negócio (sem código 401/403), incluindo registro não encontrado e falhas do provedor Dataprev; ou exceção não tratada.	ResponseListMessage
401 Unauthorized	API Key ausente, inválida, expirada ou substituída, ou usuário de integração bloqueado, desativado ou excluído.	ResponseListMessage com código "401" (ou vazio, quando gerado pelo middleware)
403 Forbidden	Usuário autenticado sem a permissão exigida.	Vazio
404 Not Found	Rotas .../current quando o registro acompanhado ainda não existe (ex.: document-requests/current antes de qualquer pedido, signature-requests/current antes da primeira assinatura). Um id inexistente, por outro lado, devolve 400 com o código "não encontrado" do módulo (ex.: 1010001, 4050001, 4060001).	Vazio

Erro genérico de exceção não tratada

Qualquer falha inesperada vira:

{ "messages": [{ "code": "9999999", "text": "Erro interno" }] }

Use 9999999 como sinal de "erro não classificado": repita a chamada após alguns segundos e, se persistir, informe o suporte com data, hora e rota.

Códigos de erro por módulo

Os códigos são agrupados por um prefixo por módulo.

Prefixo	Módulo
1006xxx	Assinatura Eletrônica
1010xxx	Empréstimos e Simulações
101040xxx	Empréstimos › Pedido de documento (formalização)
1171xxx	Consultas Externas — ver Consultas Externas
1172xxx	Modelos de texto (usados pelo termo de autorização)
1173xxx, 1174xxx	Jornadas — ver Jornadas
4050xxx	Consignado Privado › Vínculos empregatícios
4051xxx	Consignado Privado › Dados do trabalhador
4053xxx	Consignado Privado › Saldo FGTS
4060xxx	Termos de Autorização
9507xxx	Banco Semear (autorregulação CLT) — ver Consultas Externas
9508xxx	Nova Vida (bureau) — ver Consultas Externas
9509xxx	Alertaki (Receita Federal) — ver Consultas Externas

Na maioria dos módulos o código tem 7 dígitos e o prefixo são os quatro primeiros. Alguns submódulos usam códigos de 9 dígitos (ex.: 101040001, do pedido de documento): compare sempre o código inteiro, e não só o começo. 1006xxx e 1010xxx são módulos diferentes, apesar de ambos começarem por 10.

Autenticação

Uma API Key ausente, inválida, expirada ou substituída não gera código de módulo: a requisição é recusada com 401 Unauthorized (ver Autenticação).

Termos de Autorização

code	text
4060001	Termo de Autorização não encontrado
4060002	Tipo do Termo de Autorização inválido
4060003	Status do Termo de Autorização inválido
4060004	Titular dos dados (Subject) é obrigatório
4060005	Documento do titular dos dados é obrigatório
4060006	Tipo de pessoa do titular inválido
4060007	Tipo de documento do titular inválido
4060008	Provedor do Termo de Autorização inválido
4060010	Papel do signatário inválido
4060011	Tipo de autenticação da assinatura inválido
4060012	Canal da autorização inválido
4060014	Termo de Autorização já revogado
4060015	Vigência inválida: expiração anterior ao início
4060016	Termo de Autorização não pode ser assinado no status ou vigência atual
4060017	Documento do signatário é obrigatório
4060018	Informe ao menos uma assinatura

Um tipo de documento do signatário inválido é recusado com o código 1006009, da Assinatura Eletrônica. Quando o termo informa um modelo de texto (templateId), valem também:

code	text
1172001	Modelo não encontrado
1172015	Modelo inativo
1172016	O Modelo informado não é do tipo esperado

A recusa da Dataprev não volta como erro no POST: ela acontece em segundo plano, depois do aceite, e leva o termo a rejected (evento authorization_term.rejected).

Consignado Privado › Vínculos

code	text
4050001	Consulta de vínculos não encontrada
4050002	Informe o termo de autorização do trabalhador
4050003	Termo de autorização não encontrado
4050004	Termo de autorização não está ativo ou expirou
4050005	Termo de autorização sem token do provedor
4050006	Erro ao consultar os vínculos do trabalhador no provedor

Consignado Privado › Dados do trabalhador

code	text
4051001	Consulta de dados do trabalhador não encontrada
4051002	Informe o termo de autorização do trabalhador
4051003	Termo de autorização não encontrado
4051004	Termo de autorização não está ativo ou expirou
4051005	Termo de autorização sem token do provedor
4051006	Erro ao consultar os dados do trabalhador no provedor
4051007	Informe o vínculo empregatício a consultar
4051008	Vínculo empregatício não encontrado
4051009	O vínculo informado não pertence ao trabalhador do termo de autorização
4051010	O vínculo informado não possui matrícula ou inscrição do empregador

Consignado Privado › Saldo FGTS

code	text
4053001	Consulta de saldo FGTS não encontrada
4053002	Informe o termo de autorização do trabalhador
4053003	Termo de autorização não encontrado
4053004	Termo de autorização não está ativo ou expirou
4053005	Termo de autorização sem token do provedor
4053006	Erro ao consultar o saldo FGTS do trabalhador no provedor
4053007	Informe o vínculo empregatício a consultar
4053008	Vínculo empregatício não encontrado
4053009	O vínculo informado não pertence ao trabalhador do termo de autorização
4053010	O vínculo informado não possui matrícula ou inscrição do empregador

As consultas de vínculos, dados do trabalhador e saldo FGTS são processadas em segundo plano: 4050006, 4051006 e 4053006 não voltam no POST, e a falha do provedor aparece depois na própria consulta, com status = error e o motivo em status.note.

Na consulta de saldo FGTS, os motivos mais comuns devolvidos pela Dataprev são IV (trabalhador não autorizou a consulta ao FGTS no aplicativo da Carteira de Trabalho Digital, ou a autorização de 30 dias expirou) e TS (vínculo encerrado).

Assinatura Eletrônica

Ver Assinatura Eletrônica. O módulo ainda não expõe rotas REST; os códigos abaixo são os da camada de domínio e passam a ser devolvidos quando os endpoints forem publicados.

code	text
1006001	Assinatura não encontrada
1006002	Tipo da Assinatura inválido
1006003	Status da Assinatura inválido
1006004	Provedor de Assinatura inválido
1006005	Fluxo de Assinatura inválido
1006006	Funcionalidade de origem da Assinatura inválida
1006007	Informe ao menos um signatário
1006008	Informe ao menos um documento
1006009	Tipo de documento do signatário inválido
1006010	Documento do signatário é obrigatório
1006011	Informe e-mail ou telefone do signatário
1006012	Ação do signatário inválida
1006013	Canal de envio do signatário inválido
1006014	Papel do documento inválido
1006015	Origem do documento inválida
1006016	Arquivo do documento é obrigatório
1006017	Qualificação do signatário inválida
1006018	Tipo de autenticação inválido
1006019	Tipo de rubrica inválido
1006021	Signatário do requisito não encontrado no envelope
1006022	Documento do requisito não encontrado no envelope
1006023	Prazo inválido: anterior à data de envio
1006024	Expiração inválida: anterior à data de envio
1006025	Assinatura já enviada ao provedor e não pode mais ser editada
1006026	Assinatura já cancelada
1006027	Assinatura já concluída
1006028	Tipo de evento da Assinatura inválido
1006029	Origem do evento da Assinatura inválida

Empréstimos e Simulações

code	text	Onde ocorre
1010001	Empréstimo não encontrado	Assinatura, desembolso, averbação
1010002	Proposta já integrada	Assinatura, desembolso, averbação de contrato já integrated
1010003	Produto inválido	Simulação, emissão
1010004	Número de parcelas inválido	Simulação, emissão
1010005	Taxa mensal inválida	Simulação, emissão
1010006	Valor da parcela inválido	Simulação, emissão
1010007	Valor do desembolso inválido	Simulação, emissão
1010008	Valor do principal inválido	Simulação, emissão
1010009	MonthlyRate (ou Rate) deve ser maior que zero ou informe dados suficientes para inferi-la	Simulação, emissão
1010010	ID do produto inválido	Simulação, emissão com productId
1010011	Valor do principal deve ser maior que zero	Simulação, emissão
1010012	Erro no cálculo do empréstimo	Simulação, emissão, desembolso
1010013	Tipo de empréstimo inválido	Simulação, emissão
1010014	Status atual da proposta não permite esse tipo de alteração	Desembolso de contrato em stage = contract
1010015	Nenhuma data de desembolso encontrada	Desembolso com data fora dos cenários calculados
1010016	Provedor de serviços não encontrado	Desembolso sem banco liquidante configurado
1010016	Provedor de serviços não encontrado	Averbação de consignado privado sem provedor registrado para a processadora
1010022	Empréstimo já averbado	Averbação de contrato com endorsementDate preenchida ou status = endorsement
1010023	Averbação do empréstimo já está em processamento	Averbação de consignado privado enquanto o contrato está em status = endorsement_processing
1010025	Tomador do empréstimo não encontrado para assinatura	Formalização (signature-requests) de contrato sem tomador com CPF
1010025	Consignado privado não encontrado neste empréstimo	Envio do contrato à Dataprev de empréstimo sem registro de consignado privado
1010026	E-mail do tomador é obrigatório para gerar o link de assinatura	Formalização (signature-requests)
1010027	O empréstimo não pode ser enviado para assinatura no status atual	Formalização de contrato já assinado, integrado ou cancelado
1010028	O provedor de assinatura não devolveu o link de assinatura	Processamento da formalização (em lastError do pedido); nova jornada sem signatário pendente com link
1010029	Nenhuma assinatura eletrônica encontrada para o empréstimo	signature-requests/current/sync e signature-requests/current/journeys
1010033	A assinatura eletrônica do empréstimo não está aguardando assinatura; gere um novo link de assinatura	signature-requests/current/journeys com a assinatura concluída, recusada, cancelada ou expirada

O código 1010025 é usado com dois textos diferentes, conforme a rota; diferencie pelo contexto da chamada.

Empréstimos › Pedido de documento (formalização)

O texto destes erros fica no próprio pedido (lastError e status.note, sem o código) e não volta na resposta de POST /v5/loans/{loanId}/signature-requests. Ver Empréstimos › Formalização.

code	text
101040001	Tipo de requisição de documento não suportado
101040002	Empréstimo da requisição de documento não encontrado
101040003	Processamento interrompido
101040004	A requisição de documento terminou sem resultado

Os erros de regra que encerram o pedido — como 1010028 ou 1174005 (endereço da página da jornada não configurado para a empresa) — também aparecem pelo texto em lastError, separados por | quando há mais de um.

Averbação na Dataprev (consignado privado)

Ocorrem na emissão e na edição do empréstimo (validação prévia) e na chamada de averbação. Como a averbação na Dataprev é processada em segundo plano, 9503101 e 9503114 não voltam na resposta da chamada: são registrados na nota do status do contrato ("Averbação recusada: ..."). Ver Empréstimos › averbação.

code	text
9503101	Erro ao averbar o empréstimo na Dataprev
9503102	Empréstimo sem a consulta de dados do trabalhador
9503103	Informe o CPF do trabalhador
9503104	Informe a matrícula do trabalhador no empregador
9503105	Informe um tipo de inscrição do empregador aceito pela Dataprev
9503106	Informe o número de inscrição do empregador
9503107	Informe o número do contrato
9503108	Informe a data de assinatura ou de emissão do contrato
9503109	Informe a data do primeiro vencimento
9503110	Informe a data do último vencimento
9503111	Informe o número de parcelas
9503112	Informe o valor da parcela
9503113	Informe o valor liberado do empréstimo
9503114	A Dataprev não confirmou a averbação do empréstimo (a mensagem do provedor vem anexada)
9503115	Trabalhador inelegível para o consignado privado
9503116	Trabalhador bloqueado para empréstimo consignado (o tipo de bloqueio vem anexado)

Envio do contrato à Dataprev (consignado privado)

Ocorrem no envio da CCB e das evidências da formalização depois da averbação. Os documentos e dados vêm da assinatura concluída do empréstimo. 9503130 não volta na resposta da chamada: é registrado em contractInformationMessage. Ver Empréstimos › envio do contrato.

code	text
9503130	Erro ao enviar o contrato e os documentos à Dataprev
9503131	O empréstimo precisa estar averbado na Dataprev antes do envio do contrato
9503132	A assinatura não tem a CCB assinada
9503133	Arquivo da CCB assinada não encontrado
9503134	A assinatura não tem a data e hora em que a CCB foi assinada
9503135	A assinatura não tem o IP de onde a CCB foi assinada
9503136	A assinatura não tem selfie e documento oficial com foto para comprovar a formalização
9503137	O envio do contrato à Dataprev já está em processamento
9503138	Nenhuma assinatura concluída encontrada para o empréstimo

Desaverbação na Dataprev (consignado privado)

O texto destes erros fica em exclusionMessage do registro de consignado privado quando a desaverbação automática termina com erro, junto com o evento private_payroll_loan.exclusion_failed. Não voltam em nenhuma chamada do integrador.

code	text
9503140	Erro ao excluir a averbação do empréstimo na Dataprev
9503141	Empréstimo sem os dados do Crédito do Trabalhador
9503142	O empréstimo não está averbado na Dataprev
9503143	O empréstimo não está mais aguardando desembolso
9503144	O desembolso do empréstimo já foi validado ou concluído pelo pagador
9503145	Empréstimo sem o número do contrato averbado
9503146	A exclusão da averbação na Dataprev já está em processamento

Dados do consignado privado no empréstimo

Ocorrem na emissão e na edição do empréstimo, ao resolver o bloco privatePayroll. Ver Empréstimos › privatePayroll.

code	text
9504102	Consulta de dados do trabalhador não encontrada
9504104	Consulta de saldo FGTS não encontrada
9504105	Percentual das verbas rescisórias dado em garantia maior que o disponível
9504106	Garantias de FGTS disponíveis insuficientes para cobrir 100% do empréstimo
9504107	Tipo de chave PIX não permitido para o Crédito do Trabalhador (chave CNPJ)
9504108	A chave PIX do tipo CPF deve ser o CPF do tomador