Dado pessoal ou sensível deve ser mascarado em outputs, logs e exemplos. Todos os valores desta página são fictícios.
O que é
Os erros que aparecem de fato na integração do consignado privado, agrupados pela etapa em que aparecem, com causa e ação corretiva. Cada linha responde: por que aconteceu e o que fazer agora.
Quando usar
Quando uma chamada devolve 400, 403 ou 409 e a mensagem não é autoexplicativa.
Quando a operação entra em Disapproved, Revision, WarrantyRevision ou PaymentRevision.
Antes de abrir chamado: a maior parte dos casos abaixo se resolve sem a UY3.
Não existe autorização Approved para o CPF, ou a autorização existente já não é aceita.
Confirme o status na listagem. Se estiver Approved e a consulta continuar recusando, a autorização venceu: colete novo consentimento e registre outra.
Margem retornada zerada ou insuficiente
Trabalhador sem margem livre — em geral por outros contratos consignados ativos — ou vínculo encerrado.
Não há operação possível agora. Reconsulte mais tarde; não force a proposta.
Vínculo não encontrado
CNPJ do empregador ausente na consulta, ou empregador sem registro na averbadora.
Envie employerRegistrationNumber e confirme com a UY3 se o empregador está integrado.
Consulta por personId devolve vazio, por CPF funciona
O personId informado é de outro correspondente, ou o cadastro não existe ainda.
Antes do cadastro, consulte por registrationNumber. Depois dele, por personId.
Simulação
Duas coisas diferentes se parecem aqui, e confundi-las custa tempo. Não haver oferta elegível e não haver resultado para uma simulação específica têm causas e ações distintas.
Sem oferta elegível
Sem resultado para esta simulação
O que aconteceu
Nenhum produto habilitado atende àquele trabalhador, com aquela margem e aquele vínculo.
Existem ofertas para o trabalhador, mas nenhuma com os parâmetros que você pediu.
Como identificar
Uma simulação sem restrição de valor nem de prazo também volta vazia.
Uma simulação sem restrição volta com ofertas; a sua, com filtros, volta vazia.
Causa típica
Margem insuficiente, vínculo não localizado, nenhum produto Price habilitado para a categoria.
Valor pedido acima do que a margem suporta, prazo fora da faixa do produto, taxa fixada fora da faixa.
Ação
Reveja margem e vínculo. Se estiverem certos, é caso de habilitação de produto — acione a UY3.
Ajuste os parâmetros. Nenhuma chamada à UY3 é necessária.
Como diagnosticar, na prática: repita a simulação semrequestedValue, sem rangePaymentAmounts, sem rangeNumberOfPayments, sem productIds e sem interestRate — só com CPF e vínculo. Essa chamada responde a pergunta "existe alguma oferta para este trabalhador?". Se ela volta com ofertas, o problema estava nos seus filtros; se volta vazia, o problema é elegibilidade.
Por que a etapa de ofertas parecia contradizer isso. A simulação de ofertas devolve as condições possíveis para os parâmetros informados. Quando ela volta vazia, isso não significa que o trabalhador não tenha oferta nenhuma — significa que não há oferta naquele recorte. É por isso que a chamada sem filtros acima é o teste que separa os dois casos.
Sintoma
Causa provável
Ação corretiva
Simulação vazia com filtros, cheia sem filtros
Filtros estreitos demais.
Amplie rangeNumberOfPayments, reduza requestedValue ou remova productIds e interestRate.
Simulação vazia também sem filtros
Margem insuficiente, vínculo não localizado, ou nenhum produto habilitado atende.
Reveja o passo de margem. Persistindo, é habilitação de produto — acione a UY3.
Simulação vazia só ao pedir um valor
O valor pedido não cabe na margem, ainda que a margem exista.
Reduza requestedValue, ou simule por parcela com calculateByValue: "Payment".
400 na simulação por valor
calculateByValue é Gross/Liquid sem requestedValue, ou Payment sem rangePaymentAmounts.
Preencha o par correspondente ao modo escolhido.
Simulação sempre no valor máximo
Nenhum valor pedido foi informado: o comportamento padrão é usar a margem total.
Informe calculateByValue + requestedValue para simular abaixo da margem — ver 3. Operação.
Nenhuma oferta apesar de o produto estar habilitado
O produto não é do modelo de cálculo Price. As rotas de oferta do Crédito do Trabalhador listam só produtos Price.
Confirme o modelo de cálculo do produto contratado com a UY3, ou use a simulação por amortização (POST /v1/Amortization).
Proposta
Sintoma
Causa provável
Ação corretiva
Proposta recusada por expiração
expirationDate no passado, ou empregador aceitou depois do prazo.
Gere nova proposta com validade futura.
Parcela recusada na revalidação da oferta de leilão
A margem caiu entre a proposta e o aceite do empregador.
Reconsulte a margem e refaça a simulação com o valor novo.
400 com reforço FGTS
hasWarranty marcado como true sem o saldo FGTS informado.
Informe fgtsBalanceInCents (e a multa rescisória, quando houver) ou desligue o reforço.
Criação da operação
Sintoma
Causa provável
Ação corretiva
Tomador não vinculado ao usuário ou correspondente selecionado
O personId existe, mas pertence a outro correspondente ou grupo.
Use um tomador do seu escopo, ou solicite a atribuição do cadastro ao seu correspondente.
400 de periodicidade
paymentPeriodicity diferente de { "every": 1, "periodicity": "Monthly" }.
O consignado privado é mensal a cada 1 mês, porque o desconto acompanha a folha. Corrija o objeto.
400 de modelo de cálculo não suportado
amortizationType divergente do modelo do produto contratado, ou valor legado consignado.
Envie price ou sac, conforme o produto.
400 em calculationType
Envio de Price ou SAC nesse campo.
calculationType é o critério de contagem de dias (V360DiasCorridos e afins). O modelo vai em amortizationType.
400 de taxa fora da faixa
apr fora da faixa de taxa do produto, ou igual a zero.
Use a taxa devolvida pela simulação. apr é mensal, em porcentagem.
400 de prazo fora da faixa
numberOfPayments fora da faixa de prazo do produto.
Use o prazo devolvido pela simulação.
Valor da operação cem vezes menor que o esperado
requestedAmount enviado em reais e não em centavos.
Nova operação para o mesmo trabalhador recusada por falta de margem, logo após um cancelamento
O cancelamento ainda está em processamento: a margem só volta a ficar livre quando ele conclui.
Acompanhe a operação anterior até Canceled antes de recontratar.
400 ao excluir a operação
Exclusão só é permitida em Draft, Revision, Disapproved e Canceled.
Cancele primeiro e depois exclua, se necessário.
Como reagir a cada erro
Ordem de diagnóstico, do mais provável ao menos:
Releia a mensagem da resposta. As validações de negócio do consignado privado (periodicidade, faixa de taxa, faixa de prazo, margem) vêm com texto explícito.
Confira o status atual com GET /v1/CreditNote/{id}. Boa parte dos 400 e 409 é ação certa no status errado — ver 4.1 Eventos e notificações.
Confira a unidade e o formato. Valor em centavos contra valor em reais, e competência com dia, mês e ano. É a causa mais frequente de operação criada com número errado. Ver Convenções de dados.
Confira os identificadores contra os cadastros: personId, bankAccountId, productId — e o CPF, que é o que liga a autorização ao cadastro.
Isole a simulação. Antes de concluir que não há oferta, rode a simulação sem filtros. Separa elegibilidade de parâmetro em uma chamada.
Só então acione a UY3, com o id da operação, o horário da chamada e o corpo enviado — com os dados pessoais mascarados.
Orientação técnica. A classificação de dado pessoal, a base legal do tratamento e a guarda de documentos de consentimento são competência do Compliance/Jurídico da UY3 (LGPD, Lei 13.709/2018, art. 7º e art. 37). Esta página não substitui parecer.
O que acontece depois
Erro corrigido no rascunho: reenvie para aprovação e a operação retoma o fluxo. Erro corrigido depois de uma devolução para revisão: encerre a revisão pela rota indicada e a operação volta para a etapa seguinte da esteira, sem recomeçar.
API Docs
Início
Documentação
Referência de API
Copiar para LLM