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.
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 rConcurrencia
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.