Suporte

A maioria dos problemas de integração cai em um pequeno número de categorias, e cada uma tem um sintoma característico. Percorra esta página primeiro — é mais rápido do que abrir um ticket, e se não resolver, a última seção diz exatamente o que reunir para que o ticket seja respondido em uma única rodada.

Autodiagnóstico por sintoma

401 no GET /v1/verify/:id, mas a mesma chave funcionou no /init

Leia o campo error antes de mexer na chave.

Se ele disser secret_key_required, a chave é válida — é a família errada. Resultados exigem uma chave secreta (qv_sec_ / qv_sect_), porque uma chave publicável fica visível no código-fonte da sua página. Rotacionar a chave não vai ajudar. Autenticação.

Se ele disser invalid_api_key, confira o prefixo. Os prefixos de teste são qv_pubt_ e qv_sect_ — não qv_pub_test_. Confira também se a chave não foi revogada; a revogação tem efeito imediato, sem período de tolerância.

Todo upload retorna 400

Confira detail.reason.

missing_upload_token significa que o cliente montou os próprios headers em vez de repassar os que o /init retornou. Uploads não usam a sua chave de API — eles se autenticam com X-Veridia-Upload-Token, que vive dentro de slot.headers. Repasse esse objeto literalmente. Enviando as imagens.

not_a_jpeg significa que o corpo não é um JPEG. PNG, HEIC e WebP são rejeitados — converta no cliente.

bad_size significa menos de 100 bytes ou mais de 8 MB.

O /submit retorna doc_front_not_uploaded e você tem certeza de que fez o upload

O upload quase certamente falhou e a falha foi engolida. Logue o status e o detail.reason de cada PUT e releia a seção anterior.

429 mesmo com tráfego baixo

Você está batendo no limite por IP (100 requisições / 60 s), não no limite por tenant. Ele é checado antes de a sua chave de API ser lida, cobre o endpoint de upload, e uma verificação com liveness ativo faz cerca de 26 requisições a partir de um único dispositivo. Vários usuários mobile atrás de um mesmo endereço CGNAT esgotam esse limite enquanto os seus contadores de tenant parecem ociosos. Rate limits.

Usuários aprovados ficam presos em pendente — ou usuários rejeitados ganharam conta

Você quase certamente está ramificando por status em vez de verdict.

status: "completed" significa que o pipeline rodou. Não significa que a pessoa passou; uma rejeição também chega a completed. Confira os dois campos. GET /v1/verify/:id.

A imagem espelhada desse bug: um threshold escrito como scores.faceMatch. A chave é face_match, em snake_case. Em JavaScript a versão camelCase é undefined, undefined < 70 é false, e a checagem silenciosamente nunca dispara.

Os webhooks estão chegando, mas nada acontece

Confira o campo sobre o qual você faz o switch. O tipo do evento é type, não event. Handlers escritos contra event caem no branch default, retornam 200 OK e não processam nada — então, do nosso lado, a entrega parece perfeitamente saudável. Webhooks.

O widget mostra um erro genérico

O widget renderiza uma única mensagem genérica para a maioria das falhas, então o texto na tela não vai dizer qual delas é. Escute o evento veridia:error e leia e.detail.code.

Em uma conta trial ou esgotada, a causa subjacente mais comum é insufficient_credits (402), levantada durante a autenticação no /init.

A verificação está em failed

failed não é uma rejeição. Significa que o pipeline não conseguiu chegar a uma conclusão, e não há verdict para ler. Trate como repetir-ou-escalar, não como uma decisão sobre o solicitante.

Onde as coisas ficam no painel

O que você precisa	Onde
Criar ou revogar chaves de API	API keys
URL do webhook e segredo de assinatura	Settings → Webhook
Histórico de entrega dos webhooks, e reenfileirar uma entrega que falhou	Webhooks
Fila de revisão manual	Review
Saldo de créditos	Billing

Duas observações que economizam tickets:

• O segredo do webhook é escolhido por você, no mínimo 24 caracteres, e o campo é somente escrita. Não existe aquele momento de "copie agora, só é mostrado uma vez", e o painel não vai exibir o valor atual. Guarde-o onde a sua aplicação consiga ler, porque você não pode recuperá-lo conosco.
• Existe um único endpoint de webhook por tenant, não uma lista de endpoints com assinaturas por evento. Você recebe os três tipos de evento ou nenhum.

Antes de reportar alguma coisa

Inclua os itens abaixo. Sem eles, a primeira resposta vai ser um pedido por eles.

1. O requestId da resposta que falhou — também disponível no header de resposta X-Request-Id. É a coisa mais útil que você pode nos mandar; ele mapeia diretamente para os nossos logs.
2. O código em error e o objeto detail completo, não um print de uma mensagem genérica.
3. O método HTTP e o path, incluindo qual família de chave você usou.
4. Um verificationId se o problema for sobre uma verificação específica.
5. Timestamp com fuso horário, e se é reproduzível ou intermitente.
6. Teste ou produção, e aproximadamente qual volume você estava rodando.

Nunca nos envie uma chave de API, um segredo de assinatura de webhook ou as imagens do documento de um cliente. Não precisamos deles, e vamos pedir que você rotacione qualquer coisa que seja exposta.

O que não conseguimos fazer hoje

Dito de forma direta, para você não planejar em cima disso:

• Não conseguimos aumentar rate limits para um tenant específico. Os limites são fixos no deployment; não existe override por tenant. Planeje com base nos números publicados.
• Não existe rotação de chave com período de tolerância. Crie a chave nova, faça o deploy, confirme o tráfego e só então revogue a antiga. Fazer na ordem inversa é uma queda.
• Não existe uma lista publicada de IPs de saída para você liberar as nossas entregas de webhook em allowlist.
• Não conseguimos recuperar o seu segredo de assinatura de webhook. Você o escolheu; nós o armazenamos para verificar contra ele, não para devolvê-lo.

Referência

• Referência da API — endpoints, autenticação e o modelo de dois eixos status/verdict
• Erros — todos os códigos, e quais valem a pena repetir
• Rate limits — os dois limites, e a aritmética do CGNAT
• Webhooks — formato do payload, verificação de assinatura, retentativas
• Conformidade — o que está implementado e o que não está