> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veripay.datagora.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits y cuotas

> Límites por minuto y por mes que aplica el gateway.

Veripay aplica **dos** capas de control respaldadas por Redis:

| Capa          | Alcance                          | Default plan Startup | Header al exceder    |
| ------------- | -------------------------------- | -------------------- | -------------------- |
| Rate limit    | Por **API key** (por minuto)     | `60 req/min`         | `429 RATE_LIMITED`   |
| Cuota mensual | Por **usuario** (todas sus keys) | `1,000 req/mes`      | `402 QUOTA_EXCEEDED` |

## Cómo funciona

<Steps>
  <Step title="Per-minute (rate limit)">
    Bucket por `api_key.id` que se incrementa con `INCR` y expira a los 60s. Cuando excedes `per_minute`, devolvemos `429` con `details.remaining = 0`.
  </Step>

  <Step title="Mensual (cuota)">
    Bucket por `user_id` con clave `quota:{user}:{YYYY-MM}` que expira al fin de mes. Al exceder `monthly_quota` devolvemos `402` para que tu cliente sepa que necesita upgrade, no que reintente.
  </Step>
</Steps>

## Respuesta de rate limit

```json theme={null}
{
  "error": "RATE_LIMITED",
  "message": "Rate limit excedido",
  "details": { "remaining": 0 }
}
```

```json theme={null}
{
  "error": "QUOTA_EXCEEDED",
  "message": "Cuota mensual excedida",
  "details": { "remaining": 0 }
}
```

## Recomendaciones de cliente

<CardGroup cols={2}>
  <Card title="Backoff con jitter" icon="arrows-rotate">
    Para `429`, espera `200–800ms` aleatorio y reintenta. Nunca reintentes un `402`.
  </Card>

  <Card title="Cache lecturas" icon="database">
    El CEP de una transferencia es **inmutable**. Cachéalo después de la primera descarga; no vuelvas a pegarle al gateway.
  </Card>

  <Card title="Batch nocturno" icon="moon">
    Si conciliarás miles de movimientos, distribúyelos en una ventana larga en vez de ráfagas.
  </Card>

  <Card title="Plan Enterprise" icon="rocket">
    Sin límite de cuota y `per_minute` configurable. Contáctanos en <a href="mailto:soporte@datagora.mx">[soporte@datagora.mx](mailto:soporte@datagora.mx)</a>.
  </Card>
</CardGroup>

<Tip>
  Si ves muchos `429` aislados, **no necesariamente** necesitas más cuota: probablemente estás haciendo concurrencia descontrolada. Limita a `≤ per_minute / 60` peticiones simultáneas.
</Tip>