Rate limits y throttling
Límites configurados por API key durante acceso anticipado. Headers explícitos en cada respuesta. Comportamiento 429 documentado para que tu cliente haga back-off limpio.
Headers en cada respuesta
Cada respuesta — éxito o 429 — incluye los headers estándar de rate limiting. Tu cliente puede leerlos para hacer back-off proactivo antes de tocar el límite.
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 37
X-RateLimit-Reset: 1715784823
Retry-After: 12| Header | Significado |
|---|---|
| X-RateLimit-Limit | Tu límite por ventana actual (requests permitidos en la ventana de rate limiting). |
| X-RateLimit-Remaining | Requests restantes en la ventana actual. Cuando llega a 0, el próximo request va a devolver 429. |
| X-RateLimit-Reset | Timestamp en epoch UNIX (segundos) cuando se resetea la ventana y X-RateLimit-Remaining vuelve a X-RateLimit-Limit. |
| Retry-After | Solo presente en respuestas 429. Segundos a esperar antes de mandar el próximo request. |
Comportamiento 429
Cuando tu API key supera el límite configurado, devolvemos 429 Too Many Requests con el envelope de error estándar y el header Retry-After indicando cuántos segundos esperar.
El valor de error.code es siempre rate_limited. El message incluye el tiempo de espera para que también puedas parsearlo desde el body si tu cliente no expone el header.
{
"code": "rate_limit_exceeded",
"message": "Per-key rate exceeded. Retry after 12 seconds."
}Cómo cuenta el batch contra tu cuota
Toda la API es batch: el mismo endpoint valida 1 o N ítems. Cada ítem cuenta como una validación — un lote de 100 ítems consume 100 de tu cuota mensual. Records cuenta por registro, no por campo: un registro con 6 campos consume 1. El rate limit por segundo aplica por request, no por ítem.
- Piezas (emails · tax-ids · accounts · phones): hasta 1.000 ítems por request.
- Records: hasta 500 ítems por request.
- Un lote por encima del tope devuelve 400 batch_too_large; uno vacío, 400 empty_batch. Para datasets más grandes, paginás del lado del cliente.
Estrategia recomendada
Cuatro reglas que cubren casi todos los casos de integración con la API. Si tu workload es batch o burst-heavy, mencionalo en el formulario de waitlist para que ajustemos los límites antes de emitir la key.
- Honrá Retry-After al pie de la letra — no spamees con backoff fijo bajo cuando recibís 429.
- Implementá exponential backoff con jitter para respuestas 5xx (no para 429 — para 429 usá Retry-After).
- Cacheá respuestas idempotentes del lado del cliente. Las validaciones son determinísticas: mismo input → mismo output, así que cachear es seguro.
- Cacheá los resultados si validás contra la misma base seguido — un dato ya validado no cambia de formato. Sumá concurrencia limitada del lado del cliente para no saturar el rate limit por segundo.
Límites durante acceso anticipado
Los límites están configurados por API key. Durante acceso anticipado no publicamos un número global porque varía mucho por caso de uso — un dashboard interno y un checkout público tienen perfiles de tráfico distintos.
No inventamos un número genérico que después no podamos sostener. Pedinos el rate que necesitás al sumarte a la lista de espera y lo seteamos antes de emitir la key.
Para producción
Si estás planificando un deploy a producción y necesitás cuota mayor o garantías más explícitas, sumate a la lista de espera mencionando el volumen esperado.