API Docs Início Documentação Referência de API Copiar para LLM
CaaS Massificados · FGTS

FGTS — Erros e troubleshooting

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 FGTS, 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

Erros por etapa

Autenticação

Sintoma Causa provável Ação corretiva
401 em qualquer rota Token expirado ou header ausente. Emita um token novo e reenvie. Ver Autenticação.
403 em todas as rotas de operação Ambiente do parceiro sem habilitação para o produto FGTS. Acione a UY3: a habilitação é por ambiente, não por chamada.

Consentimento de consulta

Sintoma Causa provável Ação corretiva
Documento obrigatório ausente na etapa de garantia O termo não foi anexado, ou foi anexado com fileType diferente de Authorization. Reanexe com fileType: "Authorization". Ver 2.1 Consentimento de consulta.
409 ao anexar documento à operação Status da operação não aceita alteração de documentos. Anexe em Draft, ou aguarde a devolução para revisão.
Consentimento recusado na conferência Termo sem CPF do titular, sem autorização de registro da garantia, ou sem data de assinatura. Colete novo termo com os quatro itens exigidos e reanexe.
Termo desapareceu do cadastro PUT /v1/NaturalPerson/{id} enviado sem a coleção uploads. Reanexe. No futuro, envie null para preservar coleções.
Nenhum aviso de que o termo está velho Correto: o FGTS não tem status nem prazo de autorização. O controle de validade é seu. Guarde a data de assinatura e defina revalidação com o Compliance — ver 2.1 Consentimento de consulta.

Simulação

Sintoma Causa provável Ação corretiva
400 de modelo de cálculo não suportado amortizationType diferente de fgts. O FGTS aceita apenas fgts. Corrija o discriminador.
400 com campos desconhecidos no cálculo Envio de paymentDay, numberOfPayments, firstPaymentDate, calculationType, paymentPeriodicity, periodicity ou daysInYear. Remova. O modelo do FGTS tem cinco campos essenciais — ver 3. Operação.
400 de taxa apr fora da faixa do produto contratado, ou igual a zero. Use uma taxa dentro da faixa. apr é mensal, em porcentagem.
400 de prazo termInMonths fora da faixa de prazo do produto. Ajuste o prazo dentro da faixa.
Parcelas em mês errado paymentMonth ausente ou diferente do mês do saque-aniversário do titular. Informe o mês correto do saque-aniversário.
Valor simulado cem vezes menor ou maior requestedAmount enviado em reais e não em centavos. 150000 são R$ 1.500,00. Ver Convenções de dados.
Procurando a simulação de ofertas Este produto não tem esse caminho: não há margem consignável a comparar. Use POST /v1/Amortization. A justificativa está em 1. Visão geral.
Simulação não valida o saldo do titular Correto: o saldo antecipável não é exposto como consulta. A simulação calcula o plano, não confere o lastro. Dimensione pelo valor combinado com o titular. A conferência acontece na averbaçã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 titular do seu escopo, ou solicite a atribuição do cadastro ao seu correspondente.
400 de modelo divergente do produto O productId informado não é de FGTS. Confirme o productId de FGTS com a UY3.
400 na conta de liquidação liquidationType é EletronicTransfer sem bankAccountId. Informe a conta cadastrada.
Garantia criada sem correspondência Objeto warranty enviado no FGTS. Não envie garantia por tipo neste produto: o lastro é o saldo do titular e a averbação é etapa da esteira.
Operação criada mas sem documento uploads omitido na criação. Anexe por PUT /v1/CreditNote/{id}/upload antes do submitapproval. Sem isso a devolução vem na garantia, muito depois.
Documento assinado enviado em rascunho não foi aproveitado A coleção uploads foi enviada vazia, ou com fileType que não identifica o documento assinado. Envie o item com fileType: "SignedContract". Coleção vazia não reserva lugar — ver 3. Operação.
Documento duplicado no dossiê O mesmo arquivo foi reenviado em mais de uma etapa. Envie uma vez. O documento permanece vinculado à operação.

Envio para aprovação e averbação

Sintoma Causa provável Ação corretiva
Envio bloqueado por limite de contratos O titular excedeu o limite anual: cada saque-aniversário só pode ser antecipado uma vez. Não há operação possível neste ciclo. Confira as operações do titular com GET /v1/CreditNote?personId=....
409 ao reenviar submitapproval A operação já saiu do rascunho: depois do envio ela não aceita alteração até o fim da análise. Consulte o status antes de repetir. Ver 4.1 Eventos e notificações.
Operação parada em Warranty por muito tempo Averbação aguardando retorno do órgão, possivelmente em janela de manutenção. Aguardar. Este produto tolera espera maior que o consignado. Se passar da janela combinada, acione a UY3 com o id.
Operação em WarrantyRevision com saldo insuficiente O saldo antecipável do titular é menor que o requestedAmount contratado. Cancele e recrie com valor compatível, ou aguarde a orientação da mesa.
Reprovação sem adesão ao saque-aniversário O titular não aderiu à modalidade, ou migrou para saque-rescisão. Sem adesão não há parcela a antecipar. Confirme com o titular antes de recontratar.
Operação em ManualWarranty Averbação em tratamento manual da mesa. Aguardar contato da UY3; não recrie a operação em paralelo.

Assinatura e liquidação

Sintoma Causa provável Ação corretiva
Sem URL de assinatura A operação ainda não chegou a Signatures. Aguarde a aprovação do instrumento e reconsulte SignUrl.
Operação em PaymentRevision Conta de liquidação inválida ou titularidade divergente do CPF do titular. Corrija a conta em 2.2 Conta de liquidação. Chave Pix de terceiro é recusada.
Sem comprovante de transferência A liquidação ainda não ocorreu. Aguarde Liquidation/Finished e reconsulte.

Cancelamento

Sintoma Causa provável Ação corretiva
Nova operação para o mesmo titular reprovada logo após um cancelamento O desfazimento do registro no órgão ainda está em processamento. Aguarde a operação anterior chegar a 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:

  1. Releia a mensagem da resposta. As validações de negócio do FGTS (modelo de cálculo, faixa de taxa, faixa de prazo, limite de contratos) vêm com texto explícito.
  2. 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.
  3. Confira o objeto de cálculo. Campo de outro modelo no cálculo do FGTS é a causa mais comum de 400 neste produto: o modelo tem cinco campos essenciais, e só eles.
  4. Confira a unidade e o formato. requestedAmount é inteiro em centavos; apr é porcentagem mensal; o prazo é em meses. Ver Convenções de dados.
  5. Confira se o termo está no dossiê. GET /v1/NaturalPerson/{id} ou GET /v1/CreditNote/{id} mostram os uploads. É a conferência que evita WarrantyRevision — e ela é sua, porque neste produto a API não avisa antes.
  6. Confira os identificadores contra os cadastros: personId, bankAccountId, productId.
  7. 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 do termo 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.

Antes desta etapa

Próxima etapa

Downloads