Soporte
La mayoría de los problemas de integración caen en un puñado de categorías, y cada una tiene un síntoma distintivo. Recorré esta página primero — es más rápido que un ticket, y si no resuelve el problema, la última sección te dice exactamente qué juntar para que el ticket se pueda responder en una sola ida y vuelta.
Autodiagnóstico por síntoma
401 en GET /v1/verify/:id, pero la misma key funcionó en /init
Leé el campo error antes de tocar la key.
Si dice secret_key_required, la key es válida — es de la familia equivocada. Los resultados requieren una secret key (qv_sec_ / qv_sect_), porque una publishable key es visible en el código fuente de tu página. Rotar la key no va a ayudar. Autenticación.
Si dice invalid_api_key, revisá el prefijo. Los prefijos de test son qv_pubt_ y qv_sect_ — no qv_pub_test_. Revisá también que la key no haya sido revocada; la revocación surte efecto de inmediato, sin período de gracia.
Todos los uploads devuelven 400
Revisá detail.reason.
missing_upload_token significa que el cliente armó sus propios headers en vez de reenviar los que devolvió /init. Los uploads no usan tu API key — se autentican con X-Veridia-Upload-Token, que vive dentro de slot.headers. Pasá ese objeto tal cual. Subir las imágenes.
not_a_jpeg significa que el body no es un JPEG. PNG, HEIC y WebP se rechazan — convertí del lado del cliente.
bad_size significa menos de 100 bytes o más de 8 MB.
/submit devuelve doc_front_not_uploaded y estás seguro de que subiste la imagen
Casi con certeza el upload falló y la falla se tragó silenciosamente. Logueá el status y el detail.reason de cada PUT, y después releé la sección anterior.
429 aunque el tráfico sea bajo
Estás pegando contra el límite por IP (100 requests / 60 s), no contra el de por tenant. Se chequea antes de leer tu API key, cubre el endpoint de upload, y una verificación con liveness activo hace unas 26 requests desde un solo dispositivo. Varios usuarios mobile detrás de una misma dirección CGNAT lo agotan mientras tus contadores de tenant parecen ociosos. Rate limits.
Usuarios que fueron aprobados quedan pendientes — o usuarios rechazados obtuvieron cuenta
Casi seguro estás ramificando sobre status en vez de verdict.
status: "completed" significa que el pipeline corrió. No significa que la persona haya pasado; un rechazo también llega a completed. Revisá ambos campos. GET /v1/verify/:id.
La imagen espejada de este bug: un umbral escrito como scores.faceMatch. La clave es face_match, en snake_case. En JavaScript la versión camelCase es undefined, undefined < 70 es false, y el chequeo nunca se dispara, en silencio.
Los webhooks llegan pero no pasa nada
Revisá el campo sobre el que estás haciendo el switch. El tipo de evento es type, no event. Los handlers escritos contra event caen en la rama default, devuelven 200 OK, y no procesan nada — así que de nuestro lado la entrega se ve perfectamente sana. Webhooks.
El widget muestra un error genérico
El widget renderiza un único mensaje genérico para la mayoría de las fallas, así que el texto en pantalla no te va a decir cuál es. Escuchá el evento veridia:error y leé e.detail.code.
En una cuenta de prueba o agotada, la causa subyacente más común es insufficient_credits (402), lanzada durante la autenticación en /init.
La verificación está en failed
failed no es un rechazo. Significa que el pipeline no pudo llegar a una conclusión, y no hay ningún verdict para leer. Tratalo como reintentar-o-escalar, no como una decisión sobre el solicitante.
Dónde está cada cosa en el panel
| Qué necesitás | Dónde |
|---|---|
| Crear o revocar API keys | API keys |
| URL del webhook y secret de firma | Settings → Webhook |
| Historial de entregas de webhooks, y reencolar una entrega fallida | Webhooks |
| Cola de revisión manual | Review |
| Saldo de créditos | Billing |
Dos notas que ahorran tickets:
- El secret del webhook lo elegís vos, mínimo 24 caracteres, y el campo es de solo escritura. No hay ningún momento de "copialo ahora, se muestra una sola vez", y el panel no va a mostrar el valor actual. Guardalo donde tu aplicación pueda leerlo, porque de nosotros no lo vas a poder recuperar.
- Hay un solo endpoint de webhook por tenant, no una lista de endpoints con suscripciones por evento. Recibís los tres tipos de evento o ninguno.
Antes de reportar algo
Incluí esto. Sin eso, la primera respuesta va a ser un pedido de esto mismo.
- El
requestIdde la respuesta que falló — también disponible como header de respuestaX-Request-Id. Es lo más útil que nos podés mandar; mapea directamente a nuestros logs. - El código
errory el objetodetailcompleto, no una captura de pantalla de un mensaje genérico. - El método HTTP y la ruta, incluyendo qué familia de key usaste.
- Un
verificationIdsi el problema es sobre una verificación específica. - Timestamp con zona horaria, y si es reproducible o intermitente.
- Test o live, y aproximadamente qué volumen estabas manejando.
Nunca nos mandes una API key, un secret de firma de webhooks, ni las imágenes del documento de un cliente. No los necesitamos, y te vamos a pedir que rotes cualquier cosa que se haya divulgado.
Lo que hoy no podemos hacer
Dicho sin vueltas, para que no planifiques contando con ello:
- No podemos subir los rate limits para un tenant individual. Los límites están fijos en el deployment; no hay override por tenant. Planificá contra los números publicados.
- No hay rotación de keys con período de gracia. Creá la key nueva, deployala, verificá el tráfico, y recién ahí revocá la vieja. Hacerlo en el otro orden es una caída.
- No hay una lista publicada de IPs de salida para poner en allowlist nuestras entregas de webhooks.
- No podemos recuperar tu secret de firma de webhooks. Lo elegiste vos; lo guardamos para verificar contra él, no para devolvértelo.
Referencia
- Referencia de la API — endpoints, autenticación, y el modelo de dos ejes
status/verdict - Errores — cada código, y cuáles vale la pena reintentar
- Rate limits — los dos límites, y la aritmética del CGNAT
- Webhooks — forma del payload, verificación de firma, reintentos
- Cumplimiento — qué está implementado y qué no