> ## Documentation Index > Fetch the complete documentation index at: https://docs.unifokal.com/llms.txt > Use this file to discover all available pages before exploring further. # Erros da API > Todo código de erro da API UNIFOKAL, com o status HTTP, o que aconteceu, o que fazer e o que não fazer, cada um na própria âncora. ## Erros da API Toda resposta de erro tem o mesmo envelope, em toda rota: `{ "error": "", "message": "" }`. Trate pelo `error`, que é estável dentro de `/v1`. O `message` é para gente e pode mudar. Nenhum dos códigos abaixo cria sessão nem é cobrado. Cada código tem a própria âncora: cole o código no fim do endereço desta página, depois de um `#`, e você cai direto nele. São 107 códigos em 4 grupos. * [Criação de sessão: os erros do primeiro dia](https://docs.unifokal.com/erros.md#criacao-de-sessao) * [Criação de sessão: códigos de um módulo do flow](https://docs.unifokal.com/erros.md#criacao-por-modulo) * [Emissão de link hospedado](https://docs.unifokal.com/erros.md#link-hospedado) * [Cifra da carga do webhook, no painel](https://docs.unifokal.com/erros.md#cifra-do-webhook) ### Criação de sessão: os erros do primeiro dia Respostas de POST /v1/verification-sessions que qualquer flow pode receber. O mesmo vocabulário vale nas outras rotas da chave secreta: credencial, conta e teto por minuto respondem igual em todas. #### `validation_error` HTTP 400 **O que aconteceu.** Um campo obrigatório faltou ou veio fora do formato. A mensagem nomeia o campo, o valor aceito e o limite, e nunca repete o valor que você mandou. **O que fazer.** Leia o campo nomeado na mensagem, corrija o corpo e mande de novo. Confira também o cabeçalho Content-Type: application/json, sem ele a requisição chega sem corpo. **O que não fazer.** Não repita a mesma chamada esperando outra resposta: o corpo igual devolve o mesmo erro. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `invalid_json` HTTP 400 **O que aconteceu.** O corpo não é um JSON que se consiga ler: falta aspas ou chave, sobra vírgula, veio um caractere de controle cru (como o byte nulo) ou o texto não está em UTF-8. A recusa vem antes de qualquer regra da rota. **O que fazer.** Serialize o corpo com a biblioteca de JSON da sua linguagem, mande Content-Type: application/json e confira que nenhum texto do corpo traz caractere de controle sem escape. **O que não fazer.** Não monte o JSON concatenando texto: é o jeito mais comum de chegar aqui. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `payload_too_large` HTTP 413 **O que aconteceu.** O corpo passou do tamanho máximo que a API aceita, e nada foi lido nem criado. **O que fazer.** Mande só os campos do contrato. Imagem e documento nunca vão no corpo: o titular os envia pelo widget ou pela página hospedada. **O que não fazer.** Não divida o mesmo pedido em várias chamadas para caber: cada chamada é um pedido novo. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `unknown_policy_key` HTTP 400 **O que aconteceu.** O bloco policy trouxe uma chave que não existe. O bloco é uma lista fechada, e a chave recusada vem nomeada na mensagem. **O que fazer.** Tire a chave ou corrija o nome dela conforme a referência da criação de sessão e mande de novo. **O que não fazer.** Não trate como aviso: nada foi criado, e a política que você achou que ligou não vale para sessão nenhuma. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `unknown_monitoring_key` HTTP 400 **O que aconteceu.** O bloco monitoring trouxe uma chave que não existe. O bloco é uma lista fechada, e a chave recusada vem nomeada na mensagem. **O que fazer.** Tire a chave ou corrija o nome dela e mande de novo. Sem o bloco, a sessão herda o que o flow define. **O que não fazer.** Não conte com o monitoramento dessa sessão: a chamada foi recusada inteira. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `return_url_not_allowed` HTTP 400 **O que aconteceu.** O return\_url é https e o host dele não está na lista de destinos de retorno deste ambiente. A comparação é pelo host exato, e o curinga \*.seudominio.com.br cobre só um nível, nunca o próprio domínio. **O que fazer.** No painel, em Organização, acrescente o host à lista de destinos de retorno do ambiente da chave e mande de novo. A lista de sandbox e a de produção são separadas. **O que não fazer.** Não troque para http nem tire o return\_url para contornar: sem destino o titular termina na tela de conclusão, e http é sempre recusado. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `invalid_api_key` HTTP 401 **O que aconteceu.** A chave secreta não veio, veio sem o prefixo Bearer, não existe ou foi revogada. A mensagem diz qual dos casos. **O que fazer.** Mande o cabeçalho Authorization: Bearer seguido da chave unifokal\_test\_ ou unifokal\_live\_ do ambiente certo. Se a chave foi revogada, gere outra no painel e troque no seu cofre de segredos. **O que não fazer.** Não mande a chave secreta pelo navegador nem pelo aplicativo: ela vive só no seu servidor. Veja também: [Autenticação](https://docs.unifokal.com/autenticacao.md#auth) #### `organization_suspended` HTTP 403 **O que aconteceu.** A organização está suspensa, e toda chamada com a chave secreta para de uma vez. **O que fazer.** Entre no painel para ver o motivo da suspensão, ou fale com o suporte. **O que não fazer.** Não gire chave nem crie conta nova para contornar: a suspensão é da organização, e a chave nova cai no mesmo erro. Veja também: [Autenticação](https://docs.unifokal.com/autenticacao.md#auth) #### `account_under_review` HTTP 403 **O que aconteceu.** A conta está em revisão. Novas operações de produção ficam paradas até o fim da revisão: criar sessão, link, consulta, lote e ingestão em produção. **O que fazer.** Aguarde o fim da revisão. A leitura dos dados, a exportação e o sandbox continuam funcionando, e revogar ou girar uma chave e apagar uma verificação a pedido do titular também. **O que não fazer.** Não gire chave nem crie outra conta para contornar: a revisão é da organização, e a chave nova cai no mesmo erro. Veja também: [Autenticação](https://docs.unifokal.com/autenticacao.md#auth) #### `test_key_used_in_production` HTTP 403 **O que aconteceu.** O prefixo da chave diz um ambiente e o registro dela diz outro. O caso clássico é a chave guardada na variável errada do deploy. **O que fazer.** Use a chave do ambiente que você quer chamar: unifokal\_test\_ para sandbox, unifokal\_live\_ para produção. **O que não fazer.** Não edite o prefixo da chave à mão: o prefixo faz parte dela. Veja também: [Sandbox e produção: o que muda](https://docs.unifokal.com/ambientes.md#ambientes) #### `email_not_verified` HTTP 403 **O que aconteceu.** A conta ainda não confirmou o e-mail. A chave é válida e o flow existe, mas nenhuma sessão é criada antes da confirmação. **O que fazer.** Confirme o e-mail da conta pelo link que enviamos e conclua o onboarding no painel. **O que não fazer.** Não troque de chave: o bloqueio é da conta, não da credencial. Veja também: [Autenticação](https://docs.unifokal.com/autenticacao.md#auth) #### `credential_type_not_allowed` HTTP 403 **O que aconteceu.** Você mandou uma credencial do painel (dsk\_) numa rota que só aceita a chave secreta. **O que fazer.** Chame esta rota com a chave secreta unifokal\_test\_ ou unifokal\_live\_, do seu servidor. **O que não fazer.** Não reaproveite o token da sessão do painel na integração. Veja também: [Autenticação](https://docs.unifokal.com/autenticacao.md#auth) #### `flow_not_found` HTTP 404 **O que aconteceu.** O flow\_id não existe neste ambiente. Um flow vive num ambiente só, e o ambiente é a chave que você usou: o mesmo id não existe do outro lado. **O que fazer.** Confira o flow\_id e a chave. Flow de produção se chama com unifokal\_live\_, flow de sandbox com unifokal\_test\_. **O que não fazer.** Não tente o mesmo id com a chave do outro ambiente esperando achar o flow: crie o flow no ambiente em que vai usá-lo. Veja também: [Sandbox e produção: o que muda](https://docs.unifokal.com/ambientes.md#ambientes) #### `flow_not_live` HTTP 422 **O que aconteceu.** O flow existe, mas não está ativo: ainda é rascunho ou foi arquivado. **O que fazer.** Ative o flow no painel, ou use o flow\_id de um flow ativo, e mande de novo. **O que não fazer.** Não repita a chamada em laço: enquanto o flow não estiver ativo, a resposta é a mesma. Veja também: [Integração ponta a ponta](https://docs.unifokal.com/integracao.md#integracao) #### `module_dependency_violation` HTTP 422 **O que aconteceu.** O flow tem um módulo sem o módulo de que ele precisa para decidir, por exemplo Face Match (face) sem documento (cpf\_ocr ou doc\_global). A mensagem nomeia o módulo e o que falta. Vale na criação de sessão e de link, e na criação ou edição do flow. **O que fazer.** Edite os módulos do flow acrescentando o que a mensagem pede, ou use um flow que já tenha a composição completa, e mande de novo. **O que não fazer.** Não repita a chamada em laço nem suba a imagem do documento pela API para contornar: enquanto o flow não tiver o módulo, a resposta é a mesma. Veja também: [Integração ponta a ponta](https://docs.unifokal.com/integracao.md#integracao) #### `email_not_accepted` HTTP 422 **O que aconteceu.** O corpo trouxe email. O contato do titular nunca entra na criação de sessão: quem pergunta a pessoa e dispara o código é o widget. **O que fazer.** Tire email do corpo. O titular digita o e-mail na verificação. **O que não fazer.** Não mande o e-mail por outro campo para contornar: o widget é quem prova a posse do canal. Veja também: [Validação de canal: e-mail e telefone](https://docs.unifokal.com/modulos/canal.md#modulos-canal) #### `phone_not_accepted` HTTP 422 **O que aconteceu.** O corpo trouxe phone. O telefone do titular nunca entra na criação de sessão: quem pergunta a pessoa e dispara o código é o widget. **O que fazer.** Tire phone do corpo. O titular digita o telefone na verificação. **O que não fazer.** Não mande o telefone por outro campo para contornar: o widget é quem prova a posse do canal. Veja também: [Validação de canal: e-mail e telefone](https://docs.unifokal.com/modulos/canal.md#modulos-canal) #### `reference_id_charset` HTTP 422 **O que aconteceu.** Um identificador do pedido (o reference\_id, um id do evento de transação ou o act.external\_id) trouxe caractere fora do conjunto aceito ou caractere invisível. A mensagem nomeia o campo recusado. **O que fazer.** Use só os caracteres aceitos no campo nomeado, de preferência o id interno que você já usa. Um UUID serve. **O que não fazer.** Não ponha dado pessoal no id para torná-lo legível. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `pii_shaped_value` HTTP 422 **O que aconteceu.** Um identificador do pedido tem forma de dado pessoal. A mensagem nomeia o campo recusado, e o corpo do erro nunca devolve o valor. **O que fazer.** Troque pelo id do titular ou do pedido no seu sistema, sem dado pessoal dentro. Um UUID serve. **O que não fazer.** Não mascare o dado pessoal para passar: o id é opaco por contrato. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `insufficient_credit` HTTP 402 **O que aconteceu.** O saldo de produção não cobre o máximo que esta verificação pode custar. A mensagem diz quanto falta. **O que fazer.** Recarregue o saldo no painel (Cobrança) ou ligue a recarga automática, e mande de novo. **O que não fazer.** Não troque para a chave de sandbox em produção: o sandbox não verifica ninguém de verdade. Veja também: [Sandbox e produção: o que muda](https://docs.unifokal.com/ambientes.md#ambientes) #### `sandbox_limit_reached` HTTP 429 **O que aconteceu.** O sandbox chegou ao teto mensal de 500 sessões. **O que fazer.** Espere a virada do mês para seguir testando, ou passe a integração para produção. **O que não fazer.** Não trate como o limite por minuto: esperar alguns segundos não resolve este 429. Veja também: [Sandbox](https://docs.unifokal.com/ambientes.md#sandbox) #### `rate_limited` HTTP 429 **O que aconteceu.** A conta passou do teto de chamadas por minuto. Na criação de sessão ele é de 60 em produção e 240 em sandbox. **O que fazer.** Espere o prazo do cabeçalho Retry-After e tente de novo, com recuo exponencial se o volume for alto. **O que não fazer.** Não repita na hora nem em paralelo: cada tentativa imediata conta no mesmo teto. Veja também: [Sandbox e produção: o que muda](https://docs.unifokal.com/ambientes.md#ambientes) #### `idempotency_conflict` HTTP 409 **O que aconteceu.** Uma chamada com o mesmo reference\_id ainda está em andamento. O reference\_id é a chave de idempotência da criação. **O que fazer.** Espere a primeira terminar e repita: a repetição recebe a mesma sessão, com o cabeçalho Idempotent-Replay: true. **O que não fazer.** Não gere um reference\_id novo para escapar do conflito: ele identifica o seu usuário, não a tentativa. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `idempotency_key_reuse` HTTP 422 **O que aconteceu.** O mesmo reference\_id voltou com um corpo diferente dentro da janela em que a sessão anterior vale (15 minutos). **O que fazer.** Repita com o mesmo corpo da primeira chamada, ou espere a sessão anterior vencer para mandar o corpo novo. **O que não fazer.** Não reaproveite o reference\_id de um usuário para outro usuário. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `policy_module_not_in_flow` HTTP 422 **O que aconteceu.** O bloco policy ajusta um módulo que este flow não tem. A política é recusada com nome para você não achar que desligou algo que segue ligado. **O que fazer.** Tire a chave de política do módulo ausente, ou adicione o módulo ao flow no painel. **O que não fazer.** Não mantenha a chave esperando que ela valha quando o módulo entrar: a chamada inteira é recusada. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `policy_ubo_cap_above_flow` HTTP 422 **O que aconteceu.** policy.ubo\_max\_paid\_nodes veio acima do teto do próprio flow. O teto da sessão só aperta o do flow, nunca o afrouxa. **O que fazer.** Mande um valor menor ou igual ao do flow, ou suba o teto no flow pelo painel. **O que não fazer.** Não tente subir o gasto de uma sessão por este campo: o gasto só sobe por decisão registrada no flow. Veja também: [Cadeia societária até o beneficiário final](https://docs.unifokal.com/modulos/ubo-profundo.md#modulo-ubo-profundo) #### `pep_override_not_enabled` HTTP 422 **O que aconteceu.** policy.allow\_pep veio true num flow que recusa pessoa politicamente exposta, e este flow não permite afrouxar a política pela sessão. **O que fazer.** Mande a sessão sem policy.allow\_pep, ou peça a um proprietário ou administrador da conta para ligar a política de PEP ajustável por sessão no flow. **O que não fazer.** Não repita a chamada esperando outro resultado: a regra é do flow, e só muda no painel. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `reference_blocklisted` HTTP 422 **O que aconteceu.** O reference\_id enviado está na lista de bloqueio da sua conta, para este flow ou para a conta inteira. A sessão não foi criada, nada foi cobrado e o titular não passa pela captura. **O que fazer.** Trate a pessoa como barrada no seu sistema. Se o bloqueio não vale mais, remova a entrada da lista no painel e crie a sessão de novo. **O que não fazer.** Não troque o reference\_id para contornar o bloqueio: ele é a chave do titular no seu sistema. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `user_auth_not_enabled` HTTP 422 **O que aconteceu.** O corpo trouxe o bloco auth, mas o flow informado não roda a autenticação do usuário final. A sessão não foi criada e nada foi cobrado. **O que fazer.** Mande a sessão sem o bloco auth, ou use um flow com a autenticação ligada no painel. **O que não fazer.** Não repita a chamada esperando outro resultado: a regra é do flow. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `auth_required` HTTP 422 **O que aconteceu.** O flow informado roda a autenticação do usuário final e o corpo veio sem o bloco auth. A sessão não foi criada e nada foi cobrado. **O que fazer.** Gere no seu backend um code\_verifier aleatório, mande o SHA-256 dele em base64url como auth.code\_challenge, com code\_challenge\_method S256, e guarde o verifier para a troca do código. **O que não fazer.** Não gere o verifier no navegador nem o mande na criação: só o desafio sai do seu backend. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `session_not_supported` HTTP 422 **O que aconteceu.** O flow informado só recebe alertas do monitoramento transacional e não aceita sessão de verificação. Vale igual na emissão do link hospedado. **O que fazer.** Mande os eventos com o bloco transaction, ou crie a sessão no seu flow de verificação. **O que não fazer.** Não abra o widget para este flow: ele não tem jornada de titular. Veja também: [Monitoramento transacional](https://docs.unifokal.com/modulos/transacao-monitor.md#modulo-transacao-monitor) ### Criação de sessão: códigos de um módulo do flow Estes só existem quando o flow tem o módulo correspondente, ou quando a conta ligou um teto no painel. Sem o módulo, a porta não existe. #### `counterparty_country_invalid` HTTP 422 **O que aconteceu.** Um evento de transação trouxe em counterparty\_country um código de duas letras que não está na lista fechada de países (ISO 3166-1 alfa-2). A mensagem aponta o índice do evento, nunca o valor. **O que fazer.** Mande o código ISO 3166-1 alfa-2 do país da contraparte (por exemplo PA ou BR), ou deixe o campo de fora quando não souber. **O que não fazer.** Não reenvie o lote igual: a validação vem antes de qualquer gravação, e o lote inteiro é recusado de novo. Veja também: [PLD/FT pela regra da norma](https://docs.unifokal.com/pld-ft.md#pld-ft) #### `pld_profile_invalid` HTTP 422 **O que aconteceu.** O corpo trouxe o bloco opcional pld\_profile com um campo fora do formato. A mensagem traz o nome do campo, nunca o valor. **O que fazer.** Corrija o campo apontado conforme o perfil descrito na página de PLD/FT, ou mande a chamada sem o bloco. **O que não fazer.** Não repita a chamada igual: o bloco é validado antes de qualquer gravação, e a recusa se repete. Veja também: [PLD/FT pela regra da norma](https://docs.unifokal.com/pld-ft.md#pld-ft) #### `pld_profile_not_supported` HTTP 422 **O que aconteceu.** O corpo trouxe pld\_profile num flow sem o módulo que o lê: pld\_risk na criação de sessão, ou pld\_monitor na ingestão de transação. **O que fazer.** Ligue o módulo no flow, ou mande a chamada sem o bloco. **O que não fazer.** Não conte com o bloco aceito e ignorado: sem o módulo, a chamada é recusada, para você não achar que informou o perfil do seu cliente. Veja também: [PLD/FT pela regra da norma](https://docs.unifokal.com/pld-ft.md#pld-ft) #### `transaction_conflict` HTTP 422 **O que aconteceu.** O corpo trouxe transaction e transactions juntos. Os dois são exclusivos. **O que fazer.** Mande um evento no singular (transaction) ou o lote (transactions), nunca os dois. **O que não fazer.** Não duplique o evento nos dois campos para garantir: a chamada é recusada inteira. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `transaction_not_supported` HTTP 422 **O que aconteceu.** O bloco de transação foi para um flow sem módulo que consome transação. **O que fazer.** Mande a transação para o flow que tem o módulo transacional, ou adicione o módulo ao flow. **O que não fazer.** Não conte com o evento gravado: nada foi aceito. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `batch_too_large` HTTP 422 **O que aconteceu.** O lote transactions passou do teto de eventos por chamada. O teto vem no corpo do erro. **O que fazer.** Divida o lote em partes dentro do teto informado e mande cada parte. O external\_id evita duplicar. **O que não fazer.** Não descubra o teto por tentativa: ele já vem na resposta. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `batch_not_supported_for_gate` HTTP 422 **O que aconteceu.** O lote foi para um flow com o gate transacional síncrono, que decide um pagamento por vez. **O que fazer.** Mande cada evento no singular, pelo campo transaction. **O que não fazer.** Não espere veredito por item de um lote neste flow. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `transaction_required` HTTP 422 **O que aconteceu.** O flow contém o gate transacional e a chamada veio sem o bloco transaction. Vale na criação de sessão e na emissão de link hospedado. **O que fazer.** Mande o evento no bloco transaction. Esse flow só recebe transação. **O que não fazer.** Não abra o widget nem emita link para este flow: uma sessão de titular não teria o que perguntar a ele. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `external_id_required` HTTP 422 **O que aconteceu.** O evento de transação veio sem external\_id, que é o token de idempotência do evento. **O que fazer.** Mande um external\_id estável por evento, o mesmo em toda reentrega daquele evento. **O que não fazer.** Não gere um external\_id novo a cada tentativa: é ele que impede evento duplicado e segunda cobrança. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `amount_too_large` HTTP 422 **O que aconteceu.** amount\_cents veio acima do teto de valor aceito por evento. **O que fazer.** Confira a unidade: o valor vai em centavos, como inteiro. Corrija e mande de novo. **O que não fazer.** Não divida um movimento real em vários eventos para caber no teto. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `amount_above_flow_ceiling` HTTP 422 **O que aconteceu.** amount\_cents veio acima do teto de valor que a sua conta configurou neste flow. **O que fazer.** Confira o valor e o flow. Se o teto do flow ficou baixo, ajuste-o no construtor de flows. **O que não fazer.** Não divida um movimento real em vários eventos para caber no teto. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `currency_not_supported` HTTP 422 **O que aconteceu.** A moeda do evento não é BRL, a única aceita. **O que fazer.** Mande o valor em reais, com currency BRL. **O que não fazer.** Não converta sem registrar: o evento precisa descrever o movimento como ele aconteceu em reais. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `event_too_old` HTTP 422 **O que aconteceu.** occurred\_at está além da janela de importação de eventos antigos. **O que fazer.** Mande só eventos dentro da janela. Dentro dela, o evento antigo entra normalmente. **O que não fazer.** Não altere occurred\_at para caber na janela: a data precisa ser a do movimento. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `pending_lifecycle_not_enabled` HTTP 422 **O que aconteceu.** O evento veio com status pending num flow cujo módulo não aceita o ciclo pendente. **O que fazer.** Mande o evento já confirmado. Se ele for desfeito depois, mande a reversão. **O que não fazer.** Não mande o mesmo evento duas vezes, uma pendente e outra confirmada. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `settlement_status_invalid` HTTP 422 **O que aconteceu.** Uma liquidação ou reversão veio com status pending. Liquidação e reversão nunca chegam pendentes. **O que fazer.** Mande a liquidação ou a reversão quando ela já tiver acontecido. **O que não fazer.** Não antecipe a liquidação como pendente. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `unknown_settles_reference` HTTP 422 **O que aconteceu.** settles não aponta um evento seu no mesmo ambiente. **O que fazer.** Mande antes o evento original, no mesmo ambiente, e depois a liquidação apontando o external\_id dele. **O que não fazer.** Não aponte evento de outro ambiente: sandbox e produção não se enxergam. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `already_settled` HTTP 409 **O que aconteceu.** O alvo já tem liquidação ou reversão. A segunda do mesmo alvo é recusada. **O que fazer.** Trate como já registrado. Para desfazer um movimento, mande uma reversão do evento original. **O que não fazer.** Não repita a liquidação com outro external\_id. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `daily_ingest_cap_reached` HTTP 429 **O que aconteceu.** A organização chegou ao teto diário de eventos de transação. O lote recusado não gravou nada, e a resposta não traz Retry-After porque o balde é o dia. **O que fazer.** Pause o envio e retome no dia seguinte, a partir do lote recusado. **O que não fazer.** Não repita em laço durante o dia: a resposta é a mesma até a virada. Veja também: [Gate transacional](https://docs.unifokal.com/modulos/transacao.md#modulo-transacao) #### `esignature_document_required` HTTP 422 **O que aconteceu.** O flow contém o módulo de assinatura e a chamada veio sem document\_sha256. A emissão de link para esse flow cai no mesmo código. **O que fazer.** Mande o bloco esignature com o hash do documento. A sessão desse flow nasce pela API, não por link. **O que não fazer.** Não emita link hospedado para este flow: o link não leva o documento. Veja também: [Assinatura eletrônica](https://docs.unifokal.com/modulos/assinatura.md#modulo-assinatura) #### `esignature_not_supported` HTTP 422 **O que aconteceu.** O bloco esignature foi para um flow sem o módulo de assinatura. **O que fazer.** Tire o bloco, ou use o flow que tem o módulo. **O que não fazer.** Não conte com o documento assinado: nada foi criado. Veja também: [Assinatura eletrônica](https://docs.unifokal.com/modulos/assinatura.md#modulo-assinatura) #### `unknown_esignature_key` HTTP 400 **O que aconteceu.** O bloco esignature trouxe uma chave que não existe. A chave recusada vem nomeada na mensagem. **O que fazer.** Mande no bloco só o document\_sha256, com esse nome, e mande de novo. **O que não fazer.** Não trate como aviso: a chamada foi recusada inteira. Veja também: [Assinatura eletrônica](https://docs.unifokal.com/modulos/assinatura.md#modulo-assinatura) #### `document_blocklisted` HTTP 422 **O que aconteceu.** Na reautenticação facial, o documento da matrícula está na sua lista de bloqueio. **O que fazer.** Revise a entrada na lista de bloqueio. Se ela não vale mais, solte o bloqueio pela verificação ou por Sessões no painel. **O que não fazer.** Não matricule o mesmo titular de novo para contornar o bloqueio. Veja também: [Reautenticação facial](https://docs.unifokal.com/modulos/face-reauth.md#modulo-face-reauth) #### `reauth_rate_limited` HTTP 429 **O que aconteceu.** A conta passou do teto de tentativas de reautenticação facial. **O que fazer.** Espere o prazo do cabeçalho Retry-After, em segundos, e tente de novo. **O que não fazer.** Não repita antes do prazo: cada tentativa imediata recebe o mesmo 429. Veja também: [Reautenticação facial](https://docs.unifokal.com/modulos/face-reauth.md#modulo-face-reauth) #### `expected_address_not_supported` HTTP 422 **O que aconteceu.** expected\_address foi para um flow sem o módulo de comprovante de endereço. **O que fazer.** Tire o campo, ou use o flow que tem o módulo address\_ocr. **O que não fazer.** Não conte com o cruzamento de endereço: nada foi criado. Veja também: [Comprovante de endereço](https://docs.unifokal.com/modulos/endereco-ocr.md#modulo-endereco-ocr) #### `consultation_authorization_required` HTTP 422 **O que aconteceu.** O flow contém o módulo de custódia da autorização e a chamada veio sem o bloco consultation\_authorization. A emissão de link para esse flow cai no mesmo código. **O que fazer.** Mande o bloco com o hash do texto que o titular autorizou. A sessão desse flow nasce pela API. **O que não fazer.** Não emita link hospedado para este flow: o link não leva a autorização. Veja também: [Custódia da autorização de consulta](https://docs.unifokal.com/modulos/custodia-autorizacao.md#modulo-custodia-autorizacao) #### `consultation_authorization_not_supported` HTTP 422 **O que aconteceu.** O bloco consultation\_authorization foi para um flow sem o módulo de custódia. **O que fazer.** Tire o bloco, ou use o flow que tem o módulo. **O que não fazer.** Não conte com a autorização guardada: nada foi criado. Veja também: [Custódia da autorização de consulta](https://docs.unifokal.com/modulos/custodia-autorizacao.md#modulo-custodia-autorizacao) #### `unknown_consultation_authorization_key` HTTP 400 **O que aconteceu.** O bloco consultation\_authorization trouxe uma chave que não existe. A chave recusada vem nomeada na mensagem. **O que fazer.** Tire a chave ou corrija o nome dela e mande de novo. **O que não fazer.** Não trate como aviso: a chamada foi recusada inteira. Veja também: [Custódia da autorização de consulta](https://docs.unifokal.com/modulos/custodia-autorizacao.md#modulo-custodia-autorizacao) #### `foreign_entity_required` HTTP 422 **O que aconteceu.** O flow verifica uma empresa estrangeira e a chamada não trouxe o bloco foreign\_entity. **O que fazer.** Mande o bloco com o LEI da empresa, ou com o nome e o país dela. **O que não fazer.** Não tente pelo link hospedado: ele não leva a empresa. Veja também: [Empresa estrangeira](https://docs.unifokal.com/modulos/kyb-estrangeira.md#modulo-kyb-estrangeira) #### `foreign_entity_not_supported` HTTP 422 **O que aconteceu.** O bloco foreign\_entity foi para um flow sem o módulo de empresa estrangeira. **O que fazer.** Tire o bloco, ou use o flow que tem o módulo. **O que não fazer.** Não conte com a empresa verificada: nada foi criado. Veja também: [Empresa estrangeira](https://docs.unifokal.com/modulos/kyb-estrangeira.md#modulo-kyb-estrangeira) #### `foreign_entity_lei_invalid` HTTP 422 **O que aconteceu.** O LEI informado não confere o dígito de controle da norma. Quase sempre é erro de digitação. **O que fazer.** Confira o identificador com o cliente e mande de novo, ou mande o nome e o país. **O que não fazer.** Não leia como empresa inexistente: o identificador é que está errado. Veja também: [Empresa estrangeira](https://docs.unifokal.com/modulos/kyb-estrangeira.md#modulo-kyb-estrangeira) #### `foreign_entity_too_many_owners` HTTP 422 **O que aconteceu.** O bloco declarou mais beneficiários finais do que o teto por sessão. **O que fazer.** Declare só as pessoas naturais que controlam a empresa e mande de novo. **O que não fazer.** Não divida em várias sessões da mesma empresa para passar do teto. Veja também: [Empresa estrangeira](https://docs.unifokal.com/modulos/kyb-estrangeira.md#modulo-kyb-estrangeira) #### `unknown_foreign_entity_key` HTTP 400 **O que aconteceu.** O bloco foreign\_entity trouxe uma chave que não existe. A chave recusada vem nomeada na mensagem. **O que fazer.** Tire a chave ou corrija o nome dela e mande de novo. **O que não fazer.** Não trate como aviso: a chamada foi recusada inteira. Veja também: [Empresa estrangeira](https://docs.unifokal.com/modulos/kyb-estrangeira.md#modulo-kyb-estrangeira) #### `unknown_beneficial_owner_key` HTTP 400 **O que aconteceu.** Um beneficiário declarado trouxe uma chave que não existe. Hoje só o nome é aceito. **O que fazer.** Mande cada beneficiário só com o campo name. **O que não fazer.** Não trate como aviso: a chamada foi recusada inteira. Veja também: [Empresa estrangeira](https://docs.unifokal.com/modulos/kyb-estrangeira.md#modulo-kyb-estrangeira) #### `metadata_too_large` HTTP 422 **O que aconteceu.** O metadata passou de 15872 bytes depois de serializado em JSON UTF-8. Letra acentuada ocupa 2 bytes, e ideograma ou emoji ocupa 3 ou 4. **O que fazer.** Encurte os valores ou mande menos pares, e guarde o resto no seu sistema pela referência. **O que não fazer.** Não repita a mesma chamada: a recusa vem do tamanho e se repete igual. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `metadata_not_supported` HTTP 422 **O que aconteceu.** metadata veio junto do bloco de transação. A ingestão de transação não devolve sessão nem webhook de verificação. **O que fazer.** Tire metadata das chamadas de transação e mantenha só nas de sessão e de link. **O que não fazer.** Não use metadata para marcar transação: use o external\_id. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `origin_tag_not_supported` HTTP 422 **O que aconteceu.** origin\_tag veio junto do bloco de transação. A ingestão de transação não tem jornada a rotular. **O que fazer.** Tire origin\_tag das chamadas de transação e mantenha só nas de sessão. **O que não fazer.** Não use origin\_tag para marcar lote de transação: use o external\_id. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `spend_cap_reached` HTTP 429 **O que aconteceu.** A conta configurou um orçamento diário de gasto no painel e ele acabou hoje. Nada é cobrado nesta recusa. **O que fazer.** Espere o Retry-After, que vai até 00:00 UTC, ou suba o teto no painel. Subir passa a valer na virada do dia. **O que não fazer.** Não trate como retentativa curta: é uma pausa até a virada do dia. Veja também: [Painel de operação](https://docs.unifokal.com/painel-de-operacao.md#painel-de-operacao) #### `volume_cap_reached` HTTP 429 **O que aconteceu.** A conta configurou um teto diário de operações no painel e ele foi alcançado hoje. **O que fazer.** Espere o Retry-After, que vai até 00:00 UTC, ou suba o teto no painel. Subir passa a valer na virada do dia. **O que não fazer.** Não trate como retentativa curta: é uma pausa até a virada do dia. Veja também: [Painel de operação](https://docs.unifokal.com/painel-de-operacao.md#painel-de-operacao) #### `attempt_limit_reached` HTTP 429 **O que aconteceu.** A mesma referência (reference\_id) já tentou vezes demais num período recente. A sessão não foi criada e nada foi cobrado. **O que fazer.** Encerre a tentativa daquela pessoa e siga pelo seu atendimento. Se o caso for legítimo, fale com o suporte. **O que não fazer.** Não repita automaticamente nem troque o reference\_id para contornar: ele identifica o seu usuário, e a recusa não traz prazo de nova tentativa. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `module_quota_reached` HTTP 429 **O que aconteceu.** A organização alcançou hoje a cota diária de sessões novas com o módulo de PEP e sanções. A sessão não foi criada e nada foi cobrado. **O que fazer.** Espere o Retry-After, que vai até 00:00 UTC. Se o seu volume pede mais, fale com o suporte: a cota é ajustada por organização. **O que não fazer.** Não repita em laço curto nem crie sessão sem o módulo para contornar: a renovação de uma sessão já criada não conta de novo. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `account_event_required` HTTP 422 **O que aconteceu.** O flow contém o módulo de proteção de conta e a chamada veio sem o bloco account\_event. **O que fazer.** Mande o evento de conta (login, troca de senha, recuperação de acesso) no bloco account\_event. **O que não fazer.** Não abra o widget para este flow: ele avalia eventos de conta, não uma jornada de verificação. Veja também: [Proteção de conta](https://docs.unifokal.com/modulos/conta.md#modulo-conta) #### `account_event_not_supported` HTTP 422 **O que aconteceu.** O bloco account\_event foi para um flow sem o módulo de proteção de conta. **O que fazer.** Mande o evento para o flow que tem o módulo conta, ou adicione o módulo ao flow. **O que não fazer.** Não conte com o evento avaliado: nada foi aceito. Veja também: [Proteção de conta](https://docs.unifokal.com/modulos/conta.md#modulo-conta) #### `account_event_ip_not_public` HTTP 422 **O que aconteceu.** account\_event.device.ip veio com um endereço privado, de loopback ou de link-local. O campo precisa ser o IP público do usuário final. **O que fazer.** Mande o IP público de quem fez a ação, lido na borda da sua infraestrutura (o primeiro IP confiável do cabeçalho do seu proxy). **O que não fazer.** Não mande o IP do seu servidor, do balanceador ou da rede interna. Veja também: [Proteção de conta](https://docs.unifokal.com/modulos/conta.md#modulo-conta) #### `session_monitoring_not_supported` HTTP 422 **O que aconteceu.** O bloco session\_monitoring foi para um flow sem o módulo de monitoramento de sessão. **O que fazer.** Tire o bloco, ou use o flow que tem o módulo session\_monitor. **O que não fazer.** Não conte com a sessão monitorada: nada foi criado, e nenhum alerta sairia dela. Veja também: [Monitoramento de sessão](https://docs.unifokal.com/modulos/sessao-monitor.md#modulo-sessao-monitor) #### `reference_id_required` HTTP 422 **O que aconteceu.** O flow tem um módulo que amarra o resultado a um titular (proteção de conta, reautenticação facial, monitoramento de sessão ou dispositivo Pix) e a chamada veio sem reference\_id utilizável. **O que fazer.** Mande o reference\_id do titular, o mesmo identificador que você usa para ele no seu sistema. **O que não fazer.** Não mande um valor aleatório por chamada: sem o titular certo, o resultado não tem a quem se referir. Veja também: [POST /v1/verification-sessions](https://docs.unifokal.com/api-rest.md#post-sessions) #### `window_too_long` HTTP 422 **O que aconteceu.** session\_monitoring.window\_hours veio acima do teto da janela de monitoramento. A mensagem traz o teto. O valor é recusado com nome, nunca cortado em silêncio. **O que fazer.** Mande uma janela dentro do teto informado, ou omita o campo para usar a janela padrão. **O que não fazer.** Não programe o seu atendimento contando com uma cobertura maior que a janela aceita. Veja também: [Monitoramento de sessão](https://docs.unifokal.com/modulos/sessao-monitor.md#modulo-sessao-monitor) #### `enrollment_not_found` HTTP 422 **O que aconteceu.** Na reautenticação facial, não há matrícula biométrica utilizável para aquele reference\_id. A matrícula nasce num onboarding aprovado com documento, face match e prova de vida. **O que fazer.** Rode o onboarding do titular uma vez, num flow marcado para matricular, e depois peça a reautenticação. **O que não fazer.** Não tente matricular pela aprovação manual da fila de revisão: matrícula nasce de prova, não de decisão de operador. Veja também: [Reautenticação facial](https://docs.unifokal.com/modulos/face-reauth.md#modulo-face-reauth) #### `enrollment_locked` HTTP 422 **O que aconteceu.** A matrícula do titular travou depois de reautenticações seguidas que não bateram. **O que fazer.** Peça ao titular um novo onboarding aprovado: é ele que destrava a matrícula. **O que não fazer.** Não insista na reautenticação: enquanto a matrícula estiver travada, a resposta é a mesma. Veja também: [Reautenticação facial](https://docs.unifokal.com/modulos/face-reauth.md#modulo-face-reauth) #### `pix_device_required` HTTP 422 **O que aconteceu.** O flow contém o módulo de dispositivo Pix e a chamada veio sem o bloco pix\_device. **O que fazer.** Mande o bloco pix\_device com o fingerprint do aparelho que está sendo cadastrado. **O que não fazer.** Não abra este flow sem o aparelho: o vínculo é aparelho e titular. Veja também: [Cadastro de dispositivo Pix](https://docs.unifokal.com/modulos/pix-device.md#modulo-pix-device) #### `pix_device_module_not_in_flow` HTTP 422 **O que aconteceu.** O bloco pix\_device foi para um flow sem o módulo de dispositivo Pix. **O que fazer.** Tire o bloco, ou use o flow que tem o módulo pix\_device. **O que não fazer.** Não conte com o aparelho cadastrado: nada foi criado. Veja também: [Cadastro de dispositivo Pix](https://docs.unifokal.com/modulos/pix-device.md#modulo-pix-device) #### `pix_device_reference_required` HTTP 422 **O que aconteceu.** O flow contém o módulo de dispositivo Pix e a chamada veio sem reference\_id. **O que fazer.** Mande o reference\_id do titular dono do aparelho. **O que não fazer.** Não reaproveite o reference\_id de outro titular: o vínculo é aparelho e titular. Veja também: [Cadastro de dispositivo Pix](https://docs.unifokal.com/modulos/pix-device.md#modulo-pix-device) #### `credit_relationship_required` HTTP 422 **O que aconteceu.** O flow tem módulo de consulta de crédito e a chamada veio sem credit\_relationship. A Lei 12.414, art. 15, exige que o consulente declare a relação com o cadastrado. **O que fazer.** Mande credit\_relationship com existing ou prospective, conforme a relação comercial ou de crédito com o titular. **O que não fazer.** Não declare uma relação que não existe: a declaração é sua, e fica registrada na sessão. Veja também: [Análise de crédito](https://docs.unifokal.com/modulos/credito.md#modulos-credito) #### `credit_relationship_not_supported` HTTP 422 **O que aconteceu.** credit\_relationship foi para um flow sem módulo de consulta de crédito. **O que fazer.** Tire o campo, ou use o flow que tem o módulo de crédito. **O que não fazer.** Não mande o campo em todo flow por padrão: ele só vale onde há consulta de crédito. Veja também: [Análise de crédito](https://docs.unifokal.com/modulos/credito.md#modulos-credito) #### `credit_purpose_required` HTTP 422 **O que aconteceu.** O flow tem módulo de consulta de crédito e não declara a finalidade da consulta, que a Lei 12.414, art. 7, exige. **O que fazer.** Edite o flow no painel e declare a finalidade da consulta de crédito. **O que não fazer.** Não troque o flow por outro sem módulo de crédito esperando o mesmo resultado. Veja também: [Análise de crédito](https://docs.unifokal.com/modulos/credito.md#modulos-credito) #### `credit_requester_unverified` HTTP 422 **O que aconteceu.** A consulta de crédito exige a conta com CNPJ cadastrado e verificado, e a sua conta ainda não está assim. **O que fazer.** Cadastre e verifique o CNPJ da conta no painel e mande de novo. **O que não fazer.** Não use a conta de outra empresa: o consulente é quem responde pela consulta. Veja também: [Análise de crédito](https://docs.unifokal.com/modulos/credito.md#modulos-credito) #### `age_contest_channel_required` HTTP 422 **O que aconteceu.** O flow tem o módulo idade e o atendimento da sua conta está desligado. Em produção ele é o canal para a pessoa contestar o resultado da verificação de idade. **O que fazer.** Ligue o atendimento no painel, com o endereço do seu canal, e crie a sessão de novo. **O que não fazer.** Não tire o módulo idade do flow para contornar: a contestação é dever de quem afere a idade. Veja também: [Documento, face match e prova de vida](https://docs.unifokal.com/modulos/identidade.md#modulos-identidade) #### `age_document_path_unavailable` HTTP 503 **O que aconteceu.** O flow de aferição de idade usa a verificação por documento, e ela não está disponível no momento. **O que fazer.** Use um flow com o módulo idade e o grau de risco moderado, ou tente de novo mais tarde. **O que não fazer.** Não declare o grau moderado para um serviço com conteúdo ou produto proibido para menores. Veja também: [Documento, face match e prova de vida](https://docs.unifokal.com/modulos/identidade.md#modulos-identidade) #### `act_requires_passkey` HTTP 422 **O que aconteceu.** O corpo trouxe o bloco act, e o flow não tem o módulo passkey. O ato só é aprovado com o fator do titular. **O que fazer.** Use um flow com o módulo passkey para a sessão com ato, ou tire o bloco act da chamada. **O que não fazer.** Não tire o act e trate a sessão comum como aprovação do ato: ela não prova que a pessoa aprovou aquele ato. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) #### `passkey_not_enrolled` HTTP 422 **O que aconteceu.** O flow aprova com a passkey, e a conta deste reference\_id não tem passkey ativa que sirva para o pedido. **O que fazer.** Vincule a passkey antes, com um flow de cadastro que a vincula, ou use outro fator para esta pessoa. **O que não fazer.** Não repita a mesma chamada: sem a passkey vinculada, a resposta é a mesma. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) #### `passkey_bind_needs_authentication` HTTP 422 **O que aconteceu.** A conta já tem passkey ativa, e vincular outra exige que o flow também peça a passkey atual. **O que fazer.** Use um flow que vincula a passkey e tem o módulo passkey, para a pessoa entrar com a atual antes. **O que não fazer.** Não revogue a passkey atual só para vincular outra sem a pessoa pedir. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) #### `passkey_bind_needs_reproof` HTTP 422 **O que aconteceu.** A conta já teve passkey, e vincular de novo exige refazer a prova de identidade da pessoa. **O que fazer.** Use um flow que vincula a passkey com documento, Face Match e Liveness, ou com a reautenticação facial. **O que não fazer.** Não vincule de novo só com a prova de vida: a nova passkey precisa nascer de uma identidade provada. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) #### `unknown_act_key` HTTP 400 **O que aconteceu.** O bloco act trouxe uma chave que não existe. A chave recusada vem nomeada na mensagem. **O que fazer.** Tire a chave ou corrija o nome dela e mande de novo. **O que não fazer.** Não trate como aviso: a chamada foi recusada inteira. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) #### `act_hostile_char` HTTP 422 **O que aconteceu.** Um texto do bloco act (kind, summary ou counterparty) tem caractere invisível ou de controle, como quebra de linha ou marca de direção do texto. **O que fazer.** Mande o texto em uma linha só, sem caractere invisível, e mande de novo. **O que não fazer.** Não troque o caractere por outro parecido: o texto que a pessoa lê precisa ser o que o ato diz. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) #### `act_kind_invalid` HTTP 422 **O que aconteceu.** O act.kind veio vazio, acima de 40 caracteres ou com um tipo reservado. **O que fazer.** Mande um tipo curto do seu próprio vocabulário, como pix\_transfer ou change\_email. **O que não fazer.** Não ponha dado pessoal no tipo: ele volta no webhook. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) #### `act_summary_invalid` HTTP 422 **O que aconteceu.** O act.summary veio vazio ou acima de 140 caracteres. **O que fazer.** Escreva o resumo do que a pessoa aprova em uma frase curta e mande de novo. **O que não fazer.** Não corte o resumo no meio de uma palavra ou de um valor: a pessoa aprova o que lê. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) #### `act_counterparty_invalid` HTTP 422 **O que aconteceu.** O act.counterparty veio vazio ou acima de 80 caracteres. **O que fazer.** Mande o nome do favorecido abreviado, ou tire o campo, que é opcional. **O que não fazer.** Não mande documento do favorecido no lugar do nome. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) #### `act_amount_invalid` HTTP 422 **O que aconteceu.** O act.amount\_cents não é um número inteiro de centavos, zero ou maior. **O que fazer.** Mande o valor em centavos, como número inteiro, junto de currency BRL. **O que não fazer.** Não mande o valor em reais com casas decimais: o campo é em centavos. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) #### `act_currency_invalid` HTTP 422 **O que aconteceu.** A act.currency não é BRL, ou veio sem valor, ou o valor veio sem moeda. **O que fazer.** Mande amount\_cents e currency BRL juntos, ou tire os dois. **O que não fazer.** Não mande a moeda sozinha: moeda só vale com valor. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) #### `content_removed_by_notice` HTTP 422 **O que aconteceu.** O act.summary ou o act.counterparty repete um texto que a UNIFOKAL retirou da sua conta por uma notificação de conteúdo. Ele não volta enquanto a medida vale. **O que fazer.** Escreva o ato com outro texto. O acompanhamento do caso, e a contestação, ficam na página de notificação de conteúdo, com o protocolo que chegou por e-mail aos owners da conta. **O que não fazer.** Não troque só maiúsculas ou espaços: a comparação ignora caixa e espaço, e o texto continua recusado. Veja também: [Aprovação de ato com passkey](https://docs.unifokal.com/modulos/passkey.md#modulo-passkey) ### Emissão de link hospedado Códigos próprios de POST /v1/verification-links. Todo o resto do vocabulário da emissão é o mesmo da criação de sessão. #### `expires_in_too_long` HTTP 422 **O que aconteceu.** expires\_in veio acima do teto de validade do link. O valor é recusado com nome, nunca cortado em silêncio. **O que fazer.** Mande uma validade dentro do teto e emita um link novo quando ele vencer. **O que não fazer.** Não prometa ao titular um prazo maior que a validade aceita. Veja também: [Link de verificação hospedado](https://docs.unifokal.com/api-rest.md#link-hospedado) #### `environment_mismatch` HTTP 422 **O que aconteceu.** environment veio diferente do ambiente da chave. O ambiente é a chave. **O que fazer.** Tire o campo, ou use a chave do ambiente que você quer: unifokal\_test\_ para sandbox, unifokal\_live\_ para produção. **O que não fazer.** Não tente emitir link de produção com a chave de sandbox. Veja também: [Link de verificação hospedado](https://docs.unifokal.com/api-rest.md#link-hospedado) ### Cifra da carga do webhook, no painel Respostas das telas de chave pública e de cifra por destino, no painel. Não aparecem nas rotas da chave secreta. #### `encryption_key_missing` HTTP 409 **O que aconteceu.** Você tentou ligar a cifra de um destino sem chave pública ativa no ambiente dele. **O que fazer.** Registre a chave pública do ambiente no painel e depois ligue a cifra no destino. **O que não fazer.** Não desligue a cifra para receber em claro sem decidir isso de propósito: um destino com cifra obrigatória nunca recebe em claro. Veja também: [Webhooks e eventos](https://docs.unifokal.com/webhooks.md#webhooks) #### `encryption_key_in_use` HTTP 409 **O que aconteceu.** Você tentou aposentar a única chave ativa enquanto algum destino do ambiente exige a cifra. **O que fazer.** Registre a chave nova primeiro, confirme que ela abre as entregas, e só então aposente a antiga. **O que não fazer.** Não desligue a cifra do destino só para conseguir apagar a chave. Veja também: [Webhooks e eventos](https://docs.unifokal.com/webhooks.md#webhooks) #### `invalid_public_key_encoding` HTTP 400 **O que aconteceu.** A chave pública não está em base64 padrão, ou não está na forma canônica. **O que fazer.** Exporte a chave pública em SPKI DER e codifique em base64 padrão, sem quebras de linha. **O que não fazer.** Não cole a chave privada: o painel só recebe a pública. Veja também: [Webhooks e eventos](https://docs.unifokal.com/webhooks.md#webhooks) #### `invalid_public_key_format` HTTP 400 **O que aconteceu.** A chave enviada não é o SPKI DER de uma chave X25519 (44 bytes). **O que fazer.** Gere um par X25519 e envie a parte pública em SPKI DER, em base64. **O que não fazer.** Não envie chave RSA nem de curva P-256: o envelope usa X25519. Veja também: [Webhooks e eventos](https://docs.unifokal.com/webhooks.md#webhooks) #### `invalid_public_key_small_order` HTTP 400 **O que aconteceu.** A chave pública é um ponto de ordem pequena do X25519, que não serve para cifrar. **O que fazer.** Gere um par novo com uma biblioteca de criptografia padrão e envie a parte pública. **O que não fazer.** Não monte a chave à mão nem reaproveite chave de exemplo. Veja também: [Webhooks e eventos](https://docs.unifokal.com/webhooks.md#webhooks) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.