Patrones

Límites y concurrencia.

Cuántas solicitudes puedes lanzar, qué pasa cuando te pasas, y cómo procesar volumen alto sin sobresaltos.

Rate limit

Cada API key admite 120 solicitudes por minuto (2/s sostenido, con margen para ráfagas cortas). Las keys tvk_live_… y tvk_test_… cuentan por separado. Al superar el límite, la API responde 429 Too Many Requests: espera unos segundos y reintenta con backoff.

Reintentos recomendados

Envuelve tus llamadas en un reintento con backoff exponencial y jitter. Reintenta ante 429, 5xx y errores de conexión o de red. No reintentes ante 4xx (excepto 429): son errores permanentes de tu solicitud.

python
import time, httpx

def verificar(cedula, api_key, intentos=4):
    with httpx.Client(timeout=120) as c:
        for i in range(intentos):
            try:
                r = c.post(
                    "https://api.empresas.tverificas.com/v1/searches",
                    headers={"Authorization": f"Bearer {api_key}"},
                    json={"cedula": cedula, "endpoint": "identity_validation"},
                )
                if r.status_code < 500 and r.status_code != 429:
                    return r  # éxito o error permanente (4xx): no reintentar
            except httpx.TransportError:
                pass  # error de red o conexión → reintentar
            time.sleep(min(2 ** i, 8) + (i * 0.1))  # 1s, 2s, 4s, 8s + jitter
    return r

Concurrencia

Para llamadas síncronas directas (identity_validation), hasta ~10 solicitudes concurrentes es un punto cómodo: el servicio las atiende sin degradarse. Si necesitas más, usa lotes (abajo).

Para full_check usa el modo asíncrono (POST /v1/searches?async=true): creas la búsqueda y consultas su estado por GET /v1/searches/{id}. Así no mantienes una conexión abierta 1 o 2 minutos por cada verificación y puedes tener muchas en vuelo a la vez; solo respeta el rate limit al crearlas.

Volumen alto → usa lotes

Si vas a verificar cientos o miles de cédulas, no las lances en paralelo contra el rate limit. Envía un lote con POST /v1/batches: la plataforma las procesa en segundo plano con concurrencia controlada y te deja consultar el progreso. Es la vía diseñada para volumen: procesa del orden de cientos de verificaciones por hora sin que tengas que orquestar reintentos ni concurrencia tú mismo.