Rate limits

Cuotas de la API pública de La Pyme y cómo manejar respuestas 429.

La cuota de la API pública se aplica por organización, no por credencial individual.

Límite	Valor
Cuota principal	5000 requests por hora por organización
Burst protection	120 requests por minuto por organización
Superficie afectada	API pública autenticada (/api/v1/*)
Fuera de alcance	/health, OPTIONS, rutas internas y webhooks

Todas las API keys y todos los access tokens OAuth delegados de la misma organización comparten la misma cuota.

​

Headers

Las responses incluyen headers de rate limit. Cuando recibís 429, también recibís Retry-After.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 30
RateLimit-Limit: 5000
RateLimit-Remaining: 0
RateLimit-Reset: 30

​

Respuesta 429

{
  "request_id": "req_rate_limit_1",
  "error": {
    "type": "rate_limit_error",
    "code": "RATE_LIMITED",
    "message": "Se alcanzó el límite de solicitudes de la organización. Reintentá más tarde.",
    "retryable": true,
    "details": []
  }
}

​

Qué hacer

1. Leé el header Retry-After.
2. Esperá esa cantidad de segundos.
3. Reintentá la misma operación después de la ventana de espera.

Si tu integración maneja retries automáticos, usá Retry-After como fuente de verdad para el backoff.

​

Verificación temporalmente ocupada

Si la capacidad de verificación está agotada, la API espera hasta 1,1 segundos por un lugar y puede responder 503 antes de ejecutar la operación. Esta respuesta incluye Retry-After: 1, Cache-Control: no-store y el envelope habitual con error.code: "INTERNAL_ERROR" y error.retryable: true.

La cuota de la organización sigue usando 429. No cambies tus credenciales por un 503 de verificación.

Para reintentar sin generar otra ráfaga:

1. Esperá al menos el tiempo de Retry-After.
2. Sumá una demora aleatoria de hasta un segundo y duplicá la espera en cada intento, con un máximo de ocho segundos.
3. Hacé como máximo tres reintentos. Si sigue ocupado, mostrá el error y permití un nuevo intento más tarde.
4. En una escritura, conservá el mismo payload y la misma Idempotency-Key. El rechazo de verificación ocurre antes de consumir esa clave o producir efectos de negocio.