---
title: "Resolução de problemas"
description: "Modos de falha do TrustBridge por onde são percebidos, como cada um se manifesta e onde ler a causa, usando o X-Correlation-Id de cada resposta."
canonical: "https://docs.lacunasoftware.com/articles/trustbridge/troubleshooting"
locale: "pt-BR"
product: "TrustBridge"
last_updated: "2026-10-13"
---

# Resolução de problemas

Os modos de falha, organizados por onde são percebidos, como cada um se manifesta e onde ler a causa.
Toda resposta HTTP traz um `X-Correlation-Id`; informe-o e o operador encontra na hora as linhas do log
do Servidor e as linhas da Trilha de Auditoria da requisição.

## O Servidor não inicia

Toda inicialização recusada gera uma linha `Critical` citando a causa. A tabela completa está em
[Instalação do Servidor](https://docs.lacunasoftware.com/articles/trustbridge/server-installation#quando-o-servidor-não-inicia). A versão resumida:

| Sintoma | Causa |
|---|---|
| Uma linha citando `KeyRingProtector:` | Não há protetor, o valor não está em base64, a senha está errada ou não há chave RSA. Toda implantação precisa de um. |
| `…the Key Ring Protector configured here opens none of them` | Um protetor trocado. Restaure o antigo, ou adicione-o em `RetiredCertificates`. |
| `Certificates:Validation:License is not configured` | Não há licença da PKI. Toda implantação precisa de uma desde o Servidor 1.7.0, com ou sem cofre. Uma licença vencida não impede a inicialização; veja a próxima tabela. |
| `This Server's database did not answer in N seconds` | O banco de dados nunca respondeu na inicialização. Verifique `ConnectionStrings:TrustBridge` e se o banco de dados está em execução. No Azure SQL, verifique o acesso pela rede pública ou o private endpoint (erro 47073). |
| `…is behind the build … by N migration(s)` | `MigrateOnStart` está desligado e há migrações pendentes. |
| `…has N migration(s) applied that this build does not contain` | Uma imagem mais antiga sobre um esquema mais novo: um rollback sem restaurar o backup de antes da atualização. Ou um banco de dados criado pelo Servidor 1.2.0 ou anterior. |
| Uma linha citando `ForwardedHeaders:TrustedProxies` | Uma lista de proxies malformada: informada como um valor único em vez de indexada (`ForwardedHeaders__TrustedProxies__0`), `/0`, bits de host além do prefixo, um endereço IPv4 fora do decimal com pontos simples ou em forma IPv6, um endereço link-local, outra chave em `ForwardedHeaders`, como `KnownProxies`, ou a lista definida junto com `ASPNETCORE_FORWARDEDHEADERS_ENABLED`. A linha cita a entrada. |
| `Admin:CertificateSignIn:Enabled is on, but Admin:CertificateSignIn:WebPkiLicense is not set…` | O Acesso com Certificado precisa da licença do Web PKI, no formato de uma linha, citando o nome de host que as pessoas digitam. |
| `Admin:CertificateSignIn:Required is on, which switches passwords off, but Admin:CertificateSignIn:Enabled is off…` | Senhas desligadas sem acesso com certificado não deixariam nenhuma forma de entrar. Inverta uma das duas chaves. |
| `Workstations:ClientTimeout of … is shorter than 00:00:10…` ou `…longer than 00:05:00` | Fora da faixa, normalmente um erro de unidade. Escreva no formato `hh:mm:ss`: um `15` sozinho são quinze dias. |
| `Signer:ApiKey is required…` | Um endereço do Signer sem chave. |
| `Sessions:MaxDuration` abaixo de `DefaultDuration`, ou outra regra entre chaves | Uma configuração recusada; a linha cita as duas chaves. |
| No App Service, o container é encerrado e reiniciado em loop sem nada útil no log | Uma migração que demora mais que `WEBSITES_CONTAINER_START_TIME_LIMIT` (padrão de 230 s). Defina-o como 1800. |

## O Servidor iniciou, mas não funciona

| Sintoma | O que é | Onde olhar |
|---|---|---|
| `/` responde 200, `/healthz` responde 503 | O banco de dados caiu depois da inicialização. O contrato falha; o cofre está fechado. | A connection string, a disponibilidade do SQL Server. |
| Toda assinatura e importação no cofre é recusada, enquanto as estações de trabalho assinam normalmente | A trava do cofre: o Servidor subiu antes do banco de dados. | O aviso `VaultReadiness` na inicialização. O cofre se abre no primeiro uso depois que o banco de dados responde. |
| Um banner em todas as páginas administrativas: *A licença da PKI deste Servidor foi recusada, então nada consegue assinar* | A licença está vencida, corrompida ou não é uma licença, ou um sistema de arquivos somente leitura sem `/tmp` gravável impediu o SDK de lê-la. Nenhuma estação de trabalho da frota e nenhum Certificado do Cofre consegue assinar; as importações são recusadas. | A linha `Critical` de `LacunaPkiRuntime` na inicialização e a linha `Error` ao lado dela. [Renove a licença](https://docs.lacunasoftware.com/articles/trustbridge/operations#renovação-da-licença-do-pki-sdk) e reinicie o Servidor; num sistema de arquivos somente leitura, monte um `tmpfs` sobre `/tmp`. |
| Todo Certificado do Cofre aparece como `UNTRUSTED`, embora a licença esteja válida | Nenhuma âncora consegue terminar uma cadeia: `UseIcpBrasil` desligado sem nenhuma Autoridade Certificadora Confiável que seja raiz. | A linha `Critical` sobre o conjunto de âncoras, que diz que nenhuma âncora está configurada. |
| Toda criação de sessão responde `422 WORKSTATION_OFFLINE` desde que o Servidor foi atualizado para a 1.13.0 | As máquinas dos titulares ainda estão no Workstation 1.4.x (protocolo 4). Elas se conectam, mas não recebem desafio nem solicitação de PIN. | As linhas `Warning` que citam cada máquina ignorada no protocolo 4. Envie e ofereça o Workstation 1.5.0: veja [Ordem de atualização](https://docs.lacunasoftware.com/articles/trustbridge/operations#ordem-de-atualização-primeiro-o-servidor-depois-a-frota). |
| A faixa de status mostra *N exigem atualização* | Máquinas cujo protocolo o Servidor não aceita mais. No Servidor 1.13.0, o Workstation 1.3.0 ou anterior. | A coluna *Versão do serviço* da tela da frota. Instale nelas a versão atual à mão ou por Diretiva de Grupo. |
| Uma configuração não tem efeito | Uma das sete chaves que podem ser sobrepostas foi salva na tela **Configurações e usuários**, e a camada do banco de dados prevalece silenciosamente. | `/admin/settings`; restaure os padrões implantados. |
| O console administrativo em `http://` nunca conclui o login | Um cookie sem `Secure` em um link que a plataforma converte para HTTPS. | No App Service, `--https-only true`. Atrás do seu próprio proxy TLS, cite-o em `ForwardedHeaders:TrustedProxies` e faça-o repassar o `X-Forwarded-Proto`. |
| Atrás de um proxy, o redirecionamento do login aponta para `http://` ou para o endereço do upstream | O proxy substitui o `X-Forwarded-Proto` por `http`, ou não repassa o header `Host` do navegador. | No nginx, `proxy_set_header Host $host`, e preserve o `X-Forwarded-Proto` da borda. |
| Toda linha de auditoria registra o endereço do proxy | O proxy não está citado, então todo chamador é o proxy. Atrás de um proxy não citado, todos os navegadores também dividem uma única cota do Acesso com Certificado, e a frota inteira uma única cota de admissão. | Docker: [`ForwardedHeaders:TrustedProxies`](https://docs.lacunasoftware.com/articles/trustbridge/configuration#forwardedheaderstrustedproxies). App Service: `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true`. A linha de inicialização que começa com `Forwarded headers:` diz em quem o Servidor confia. |
| Um `Warning` na inicialização: `Forwarded headers: honoured from whoever connects …` | Uma implantação Docker que ainda usa `ASPNETCORE_FORWARDEDHEADERS_ENABLED`: qualquer cliente que alcance a porta pode informar o próprio endereço. | Cite o proxy em `ForwardedHeaders:TrustedProxies` e remova a variável. |
| As desconexões das máquinas aparecem como `closed` em `LongPolling`; o console administrativo está lento | O proxy não transporta WebSockets, então as conexões caem para long polling. | Os headers de upgrade para WebSocket no proxy. |
| Linhas `KeyRingProvider[48]` ou `XmlKeyManager[24]` em um Servidor que iniciou sem erros | O **banco de dados** está inacessível, não o protetor. | `/healthz`. |
| Uma linha `Critical` com uma linha de auditoria inteira | O banco de dados recusou uma gravação de auditoria; a linha só existe nessa entrada do log. | Guarde o fluxo de log. O console mostra um alerta. |
| Um banner de aviso em todas as páginas administrativas sobre as ACs de teste | `UseLacunaTestPki` está ligado. | Desligue a PKI de testes em tudo que não seja uma máquina de desenvolvimento. |

## Entrada no console administrativo

| Sintoma | O que é | O que fazer |
|---|---|---|
| *Nenhum certificado com CPF foi encontrado neste computador* | Só certificados e-CPF são listados: um e-CNPJ ou um certificado sem CPF nunca é oferecido. Ou o token não está conectado. | Insira o token ou cartão com o e-CPF e recarregue a página. |
| *Entrar com certificado só é possível em um computador* | Um celular ou um tablet. | Use um navegador de desktop. |
| *Para entrar com certificado, você precisa do componente Web PKI…* ou *…precisa ser atualizado* | O Web PKI está ausente ou desatualizado neste navegador. | Siga o *Instalar o Web PKI* ou o *Atualizar o Web PKI* da página. |
| *Não é possível ler certificados aqui: a licença do Web PKI deste Servidor não cobre este endereço* | `Admin:CertificateSignIn:WebPkiLicense` não cita o nome de host que as pessoas digitam, ou não é válida. | Uma licença do Web PKI para esse nome de host e, em seguida, um reinício. |
| *Esse acesso não abriu nenhuma conta* | Nenhuma conta habilitada tem o CPF do certificado como CPF vinculado. | Outro Administrador define o CPF da pessoa com **Definir CPF vinculado** na tela de contas. Ninguém define o próprio. |
| *Este Servidor não confia na autoridade que emitiu este certificado*, ou uma frase dizendo que ele expirou, foi revogado ou não pôde ser verificado | Só um veredito `ACTIVE` permite a entrada. `UNTRUSTED` normalmente é a Autoridade Certificadora Confiável dos administradores removida, ou a licença da PKI do Servidor recusada (o console administrativo mostra um banner). | A tela de Autoridades Certificadoras Confiáveis conta os administradores que cada autoridade permite entrar antes de você removê-la; renove a licença. |
| *Este certificado não traz um CPF válido como titular* | O certificado de uma Empresa. | Entre com o e-CPF da pessoa. |
| *Tentativas demais a partir deste endereço* | Dez desafios por minuto por endereço. Atrás de um proxy não citado, todos os navegadores dividem essa cota. | Aguarde um minuto; cite o proxy em `ForwardedHeaders:TrustedProxies`. |
| As senhas estão desligadas e uma conta não tem CPF vinculado | Ela não consegue entrar de forma alguma enquanto `Admin:CertificateSignIn:Required` está ligado, inclusive as contas novas. | Outro Administrador define o CPF vinculado dela. Um Administrador sozinho não tem quem defina o dele, então mantenha pelo menos dois. |
| As senhas estão desligadas e ninguém consegue entrar | Tudo o que encerra todos os acessos com certificado de uma vez: a Autoridade Certificadora Confiável dos administradores removida, uma licença da PKI recusada, uma licença do Web PKI que não cita mais o nome de host, uma atualização do navegador que quebrou a extensão, ou o CPF vinculado do último Administrador limpo. | Defina `Admin:CertificateSignIn:Required=false` e reinicie; entre com senha e corrija a causa; **depois volte a defini-lo como `true` e reinicie**. Nada vai lembrar você de desfazer isso. |

## Estações de trabalho

| Sintoma | O que é | Onde olhar |
|---|---|---|
| Instalação com código de saída 1603, log cita `SERVER_URL` | A condição de inicialização: URL vazia ou sem esquema. | Passe `SERVER_URL=https://…`. |
| Instalação com código de saída 1603, log diz que uma versão mais nova está instalada | Um downgrade. | Desinstale antes; a máquina volta como uma máquina nova. |
| A instalação é revertida em *Starting services* | O serviço se recusou a iniciar: uma `INSTALLER_KEY` que não pode ser interpretada ou um valor de Registro do tipo errado. | Log de eventos Aplicativo, origem **TrustBridge Workstation Service**. |
| *Editor: Desconhecido* na solicitação de elevação, um bloqueio do SmartScreen, ou uma diretiva que exige editor recusando o pacote | Um pacote não assinado: um build de desenvolvimento, nunca uma release. Toda versão do Workstation a partir da 1.2.1 é assinada por **LACUNA SOFTWARE LTDA**. | Obtenha o pacote da release com a Lacuna Software e verifique a assinatura com `Get-AuthenticodeSignature`. |
| Instalada, nunca aparece na fila de admissão, nada no Servidor | A URL do Servidor está errada, ou uma GPO a está sobrepondo, ou a máquina não confia na cadeia TLS. | A linha *`Server:Url` is …, supplied by …* do serviço na inicialização; `HKLM\Software\Policies\TrustBridge` em um PowerShell de 64 bits. |
| Nunca aparece, e o log da máquina diz que a requisição de admissão foi recusada | Uma de quatro causas: revogada, uma Installer Key em que o Servidor não confia, requisições demais do endereço dela ou fila cheia. O Servidor deliberadamente não diz qual. | As duas últimas se resolvem sozinhas. Procure uma linha revogada na tela **Estações de Trabalho**. |
| Está na fila, e o Tray mostra *Ainda não admitida* | Não é uma falha. | Admita-a em `/admin/admission`. |
| Admitida, mas não se conecta; o log do Servidor diz `…is newer than this server's supported window …; update the Server first` | A estação de trabalho foi atualizada antes do Servidor, por exemplo o Workstation 1.5.0 contra um Servidor anterior à 1.13.0. Ela não recebe licença, então todo certificado dela aparece como `UNTRUSTED`. | Atualize o Servidor. Veja [Ordem de atualização](https://docs.lacunasoftware.com/articles/trustbridge/operations#ordem-de-atualização-primeiro-o-servidor-depois-a-frota). |
| Admitida, mas não se conecta; a linha da frota diz `…is older than this server's supported window …; update required` | A estação de trabalho é antiga demais para o Servidor: no Servidor 1.13.0, o Workstation 1.3.0 ou anterior. | Instale a versão atual à mão ou por Diretiva de Grupo. O Servidor não consegue atualizá-la. |
| Admitida, mas não se conecta; o log do Servidor diz `A workstation assertion was refused: Expired` ou `NotYetValid` | O relógio da máquina está mais de 60 s fora. A linha traz a diferença: positiva quando a máquina está atrasada em relação ao Servidor. | A sincronização de horário da máquina. |
| Conectada, mas as sessões dos titulares dela recebem `WORKSTATION_OFFLINE` | A máquina roda o Workstation 1.4.x contra o Servidor 1.13.0, então não recebe desafio nem solicitação de PIN. | Ofereça a ela o Workstation 1.5.0. |
| Todo certificado aparece como `UNTRUSTED` | Nenhuma licença da PKI chegou à máquina: ela está Pendente, não alcançou o Servidor, foi recusada com *update the Server first*, ou a própria licença do Servidor foi recusada (o console administrativo mostra um banner). Ou nenhuma âncora consegue terminar uma cadeia. | A linha do Tray App acima da lista de certificados diz qual. Admita a máquina; renove a licença no Servidor e reinicie o Servidor, e a máquina a aplica ao se reconectar. Nada configurado na máquina fornece uma licença. |
| Um certificado aparece como `UNTRUSTED` enquanto a licença está em ordem | O emissor dele não está no conjunto de âncoras da máquina. | **Confiar no emissor**, no Registro de Certificados, que adiciona uma Autoridade Certificadora Confiável que chega à máquina. |
| Um certificado aparece como `STALE` | Não foi possível baixar a LCR da AC dele por mais tempo que a janela de tolerância (24 h). | Se a máquina consegue acessar a AC. |
| Um token está conectado, mas nenhum certificado aparece | Um middleware incomum, fora da lista fornecida; ou um módulo citado em `Certificates:Pkcs11:Modules` que não carrega. | A aba de tokens do Tray App cita o middleware que falhou e qualquer leitora com um cartão que nenhum middleware lê. O log do serviço cita o módulo. |
| Um e-CNPJ aparece no Tray App como não anunciado | O Servidor não aceita certificados de Empresa: é anterior à 1.13.0. | Atualize o Servidor. |
| O Tray App não aparece depois da instalação | Ele inicia no próximo login ou, depois de uma atualização, quando o novo serviço inicia. | Saia e entre de novo, ou inicie `Tray App\TrustBridge.TrayApp.exe`. |
| O Tray App diz *Sem conexão* | Ele não conseguiu abrir o pipe do serviço: o Workstation Service está parado ou reiniciando. | `sc.exe query "TrustBridge Workstation Service"`; o log de eventos Aplicativo. |
| Uma alteração de diretiva não teve efeito | O Registro é lido uma vez, na inicialização. | `Restart-Service "TrustBridge Workstation Service"`. |
| Uma máquina perfeitamente configurada parece vazia no Registro | Um PowerShell de 32 bits redirecionado para `WOW6432Node`. | Use um PowerShell de 64 bits. |
| Todo certificado de uma máquina aparece como `ACTIVE`, inclusive os de exemplo | `UseLacunaTestPki` ligado, ou uma seção `FakeTokens` no arquivo de configuração. | Remova os dois de qualquer máquina em que alguém assine. |

## Atualização da frota pelo Servidor

| Sintoma | O que é | O que fazer |
|---|---|---|
| Envio recusado: *O pacote não está assinado* | Um build de desenvolvimento. | Envie o pacote assinado da release. |
| Envio recusado: *O pacote está assinado por …, um certificado que o Publisher Pin deste Servidor não lista* | Não é uma release da Lacuna, ou é um pacote assinado de novo depois de sair da Lacuna. | Envie o pacote da release como a Lacuna Software o entrega. |
| Envio recusado: *A assinatura do pacote não pode ser lida* | Uma cópia danificada no caminho. | Baixe a release de novo. |
| Envio recusado: *O pacote não declara qual protocolo fala* | Uma versão do Workstation anterior à 1.3.0, ou não é um pacote do Workstation. | Envie uma versão atual. |
| Envio recusado: *O pacote fala o protocolo N, e este Servidor fala o M. Atualize o Servidor primeiro* | A versão é mais nova que o Servidor, por exemplo o Workstation 1.5.0 num Servidor anterior à 1.13.0. | Atualize o Servidor e depois envie. |
| Envio recusado: *…este Servidor só aceita os protocolos de N a M* | A versão é antiga demais para o Servidor: as máquinas que a instalassem não conseguiriam se conectar. | Envie uma versão atual. |
| Envio recusado: *A versão N já está armazenada* | Essa versão já está no Servidor. | Nada a fazer, ou exclua-a antes para substituí-la. |
| Envio recusado: *Este Servidor não consegue gravar no seu diretório temporário* | `/tmp/trustbridge-releases` está somente leitura ou cheio. | O log do Servidor cita o diretório e o motivo. Monte um volume em disco sobre ele: veja [os diretórios temporários](https://docs.lacunasoftware.com/articles/trustbridge/operations#os-diretórios-temporários). |
| No App Service, um envio grande nunca termina | O envio é uma única requisição, e o front end encerra as requisições depois de cerca de quatro minutos. | Envie por um link mais rápido. |
| Uma versão não pode ser excluída | Ela está oferecida a máquinas, inclusive revogadas. | **Retirar de todas**, na tela **Versões da Estação de Trabalho**, antes. |
| Uma máquina fica de fora de uma oferta | Ela não está Admitida, já roda essa versão ou uma mais nova, está com **Atualizações desativadas por diretiva**, ou **Precisa de atualização manual** (Workstation 1.3.0 ou anterior). | O motivo aparece ao lado do nome dela na caixa de diálogo da oferta. Atualize-a à mão ou por Diretiva de Grupo. |
| Uma máquina informa que a atualização falhou (*failed*) | O `msiexec` falhou ou desistiu: o painel de detalhes mostra o código de saída e o final do log dele. O código 1618 (outra instalação em andamento) é repetido pela própria máquina quinze minutos depois. | Corrija a causa na máquina e ofereça a versão de novo: uma versão que falhou nunca é tentada de novo sozinha. |
| Uma máquina informa que a atualização foi recusada (*refused*) | Uma das verificações da máquina falhou: hash, assinatura, carimbo de tempo, Publisher Pin, revogação, produto ou versão. | A verificação aparece na linha. Uma falha de hash normalmente é um download danificado: ofereça de novo. |
| Nada acontece depois de uma oferta | A máquina espera até dez minutos antes de baixar e, depois, espera até não haver assinatura em andamento nem solicitação de PIN aberta. Downloads acima do limite do Servidor são instruídos a voltar mais tarde. | Aguarde. Uma máquina offline recebe a oferta no próximo handshake. |

## Erros na aplicação cliente

Decida com base em `error.code`. O vocabulário completo está na página
[API REST](https://docs.lacunasoftware.com/articles/trustbridge/rest-api#o-envelope-de-erro).

| Código | Causa comum | O que fazer |
|---|---|---|
| `401 UNAUTHORIZED` | Chave ausente, digitada errado, revogada ou expirada, ou uma aplicação desativada. Todas recusadas da mesma forma. | Verifique a chave na tela **Aplicações Cliente**. |
| `401 SESSION_EXPIRED` | A sessão expirou por inatividade, foi desativada, foi substituída por uma mais nova do mesmo CPF (e CNPJ), esgotou a Franquia de Assinaturas ou estava vinculada ao cofre durante um reinício do Servidor. | Crie uma nova sessão. Nada indica qual foi o caso; isso é deliberado. |
| `400 INVALID_REQUEST` em `POST /v1/sessions` citando `cpf` ou `cnpj` | Os dígitos verificadores não conferem, ou é um valor de dígitos repetidos. | Corrija o valor na origem. Valide os dígitos verificadores no seu formulário. |
| `400 INVALID_REQUEST` em uma assinatura ou num lote | Não há `sessionId` na requisição. | Envie o id que `POST /v1/sessions` retornou. Repetir sem alterações falha da mesma forma. |
| `404 CERT_NOT_FOUND` | Nenhum certificado do CPF (e CNPJ) está disponível em lugar nenhum: o token não está conectado, a máquina não está admitida ou conectada, ou o CPF nunca recebeu um certificado. Para uma sessão com `cnpj`, também uma máquina anterior ao Workstation 1.5.0, que não anuncia e-CNPJs. | O Registro de Certificados e a tela **Estações de Trabalho**. |
| `422 CERT_NOT_ACTIVE` | Todo certificado do CPF (e CNPJ) está `EXPIRED`, `REVOKED`, `UNTRUSTED` ou `STALE`. `UNTRUSTED` muitas vezes significa que as âncoras da implantação não cobrem o emissor, ou que a licença da PKI do Servidor foi recusada. | `GET /v1/certificates/info` para ver o veredito; o Registro de Certificados para ver o emissor. |
| `401 INVALID_PIN` | Toda máquina com um certificado candidato deu uma Prova de PIN e nenhuma conferiu com o PIN enviado, e o PIN não abriu nenhum Certificado do Cofre. Normalmente um PIN errado, ou uma máquina cujo PIN em cache é outro. | Pergunte ao titular. Cinco falhas em quinze minutos bloqueiam o CPF. |
| `422 PIN_NOT_AVAILABLE` | Nada pôde ser comparado: a solicitação no Tray expirou, foi recusada ou não havia ninguém conectado para respondê-la; um Certificado A1 sem PIN do Certificado A1 definido; um Certificado do Cofre não pôde ser aberto. Ou o `details` diz que provas ou senhas demais não conferiram recentemente, então a máquina ou o cofre não é consultado de novo até elas saírem da janela. | O `details` diz qual. Para uma solicitação no Tray, o titular precisa estar na máquina dele com o Tray App em execução. Um limite esgotado se resolve sozinho. |
| `422 WORKSTATION_OFFLINE` | Toda máquina com um certificado ativo do CPF (e CNPJ) está offline, depois da tolerância de reconexão, em uma assinatura. No Servidor 1.13.0, uma máquina ainda no Workstation 1.4.x, ou uma que esgotou o limite de provas com falha para esse CPF, conta como offline para a criação de sessões. | A tela **Estações de Trabalho** e as linhas `Warning` do log do Servidor que citam as máquinas ignoradas. |
| `422 CERT_INCOMPLETE_IDENTITY` | O certificado não identifica o titular o bastante para assinar em nome dele; o `details` cita o campo que falta. | Se for o endereço de e-mail, envie `email` ao criar a sessão. Qualquer outro campo é do próprio certificado: assine com outro certificado. |
| `422 SIGN_TIMEOUT` | A assinatura não terminou dentro de `Signing:RequestBudget` (60 s). Uma máquina lenta ou um Signer lento. | A tela **Operações de Assinatura** mostra a etapa alcançada. |
| `422 SIGNER_REJECTED` | O Lacuna Signer foi acessado e recusou a requisição: normalmente o próprio documento, às vezes outra coisa que a requisição citou. O `details` traz a explicação dele. Repetir sem alterações reproduz o erro. | Leia o `details` e corrija o documento ou a requisição. |
| `502 SIGNER_ERROR` | Não foi possível consultar o Signer: inacessível, limitando requisições ou respondendo com uma falha própria. Nada foi assinado, então o mesmo documento pode ser enviado de novo quando ele voltar. Um Signer que recusa a credencial do próprio Servidor também chega aqui. | A disponibilidade do Signer, `Signer:BaseAddress` e `Signer:ApiKey`. |
| `409 DOCUMENT_NOT_READY` que nunca se resolve | A assinatura ainda está em andamento, ou uma execução foi interrompida por um reinício e o Signer ainda mantém o documento aberto. | A tela **Operações de Assinatura**; `RUN_STRANDED`. |
| `429 SERVER_BUSY` no uso normal | `Throttle:ConcurrencyLimit` baixo demais para a implantação; não é um problema do cliente. | Aumente-o. Em um pico real, tente de novo com backoff e jitter. |
| `429 TOO_MANY_PIN_ATTEMPTS` | O bloqueio por CPF, qualquer que seja o `cnpj` enviado. | Espere a janela (15 min) passar. Tentar de novo piora a situação. |
| `404 ENDPOINT_NOT_FOUND` | Uma rota sem o prefixo `/v1`. | Corrija a URL. |
| `413 DOCUMENT_TOO_LARGE` | Acima de `Signing:MaxDocumentBytes` (10 MB por padrão). | Um documento menor, ou aumente o limite sabendo o que isso custa. |
| `500 INTERNAL_ERROR` em uma assinatura, com `could not be opened by the reader this platform signs with` no log do Servidor | Um Certificado do Cofre importado antes de existir a verificação do formato legado, protegido com `pkcs5PBES2`. | Exporte de novo com `openssl pkcs12 -export -legacy` e importe outra vez. Isso exige o arquivo original. |

## Resultados de assinatura na tela Operações de Assinatura

Uma operação **Com falha** traz um código de falha e a **etapa** que alcançou: o `202` do cliente pode ter
sido respondido muito antes. `RUN_STRANDED` significa que o Servidor foi reiniciado durante a execução
e uma varredura a encerrou. Uma execução que falhou depois de o documento chegar ao Signer deixa um
documento aberto lá, que a busca informa como `409` até que a retenção do próprio Signer ou a limpeza
o encerre como `422`.

## Como obter ajuda

Envie ao suporte da Lacuna Software o `X-Correlation-Id` da requisição que falhou, a versão do
Servidor exibida no rodapé do console administrativo, a versão do pacote da estação de trabalho
mostrada na tela **Estações de Trabalho** e as linhas relevantes do log do Servidor. Para um problema
em uma estação de trabalho, acrescente as entradas do log de eventos Aplicativo com origem
**TrustBridge Workstation Service**. Nunca envie um PIN, uma chave de API, o Protetor do Chaveiro nem
a licença.