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.
{
"error": {
"code": "rate_limited",
"message": "Quota exceeded. Retry after 12 seconds.",
"request_id": "req_a1b2c3d4e5f6g7"
}
}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.
- Batch en cliente si necesitás validar muchos records — durante acceso anticipado no hay endpoint batch en /v1/. Concurrencia limitada + cache resuelve casi todos los casos.
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.