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 (la primera solicitud tras un rato de inactividad puede tardar más o rechazar la conexión mientras la infraestructura escala desde cero — ver más abajo). 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.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  # conexión rechazada durante cold-start → 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 y el reintento absorbe cualquier rechazo de cold-start. Por encima de eso, la tasa de éxito en la primera ráfaga empieza a caer si el servicio venía frío.

full_check es asíncrono: creas la búsqueda y consultas su estado por GET /v1/searches/{id}. No mantiene una conexión abierta, así que puedes tener muchas en vuelo a la vez sin contarlas como concurrencia sostenida — 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 despacha con concurrencia controlada, escala las instancias necesarias y te deja consultar el progreso. Es la vía diseñada para throughput — procesa del orden de cientos de verificaciones por hora sin que tengas que orquestar reintentos ni concurrencia tú mismo.