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

# Rate limits

> Límites por endpoint y cómo manejar respuestas 429.

## Límites por tipo de endpoint

| Endpoint group                                                                  | Rate limit              | Burst | Notas                                       |
| ------------------------------------------------------------------------------- | ----------------------- | ----- | ------------------------------------------- |
| **Read** (`GET /v1/links`, `/v1/accounts`, `/v1/accounts/{id}/movements`, etc)  | 100 req/min por API key | 20    | Mismo bucket para todos los GETs            |
| **Sync write** (`POST /v1/refresh_intents`)                                     | 10 req/min por API key  | 5     | Independiente del cooldown de 5min por link |
| **Widget tokens** (`POST /v1/widget_tokens`)                                    | 30 req/min por API key  | 10    |                                             |
| **Resources write** (`POST /v1/links/{id}/pause`, `DELETE /v1/links/{id}`, etc) | 30 req/min por API key  | 10    |                                             |
| **Webhook deliveries** (read)                                                   | 60 req/min por API key  | 20    |                                             |

<Note>
  Los límites son **por API key**, no por client. Si tienes `sk_live` + `sk_test`, cada una tiene su propio bucket. Las `pk_*` comparten bucket con su `sk_*` del mismo modo.
</Note>

## Headers en cada response

Todos los responses incluyen:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1717434120
```

| Header                  | Significa                                       |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`     | Tu límite efectivo para este bucket (req/min)   |
| `X-RateLimit-Remaining` | Cuántos requests te quedan en la ventana actual |
| `X-RateLimit-Reset`     | Unix timestamp de cuándo se resetea el bucket   |

## Cuando excedes — 429

```http theme={null}
HTTP/2 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1717434143

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Excediste el límite de 100 req/min para esta API key. Reintenta en 23 segundos."
  }
}
```

El header `Retry-After` te dice **cuántos segundos esperar antes de reintentar**.

## Manejo recomendado

```ts theme={null}
async function railFetchWithBackoff(
  path: string,
  opts: RequestInit,
  maxRetries = 3,
): Promise<Response> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(`https://api.rail.cl${path}`, opts);
    if (res.status !== 429) return res;

    if (attempt === maxRetries) return res;

    const retryAfter = Number(res.headers.get('retry-after') ?? '5');
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
  }
  throw new Error('unreachable');
}
```

## Patrones que disparan 429

| Anti-patrón                                        | Por qué te bloquea                                                                     |
| -------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Polear `/v1/refresh_intents/{id}` cada 1s          | Excedes 100 req/min en pocos minutos. Polear cada 5-10s en su lugar (o usar webhooks). |
| Listar todos los movimientos sin paginar bien      | Loop sin condición de salida = burst inmediato.                                        |
| Crear un `refresh_intent` por cada user en un cron | Hazlo escalonado o usa los syncs automáticos de Rail (cada 4h).                        |

## Pedir upgrade

Si tu use case legítimo requiere límites más altos, contáctanos en [soporte@rail.cl](mailto:soporte@rail.cl) con:

* Tu `client_id` (lo ves en el dashboard)
* Caso de uso + volumen esperado
* Endpoint/bucket específico

Subimos rate limits caso por caso para clientes con producción estable.