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

# Rate limits

> Límites de requests por minuto, headers de control y cómo manejar el 429.

## Límites vigentes

Los límites se aplican **por cuenta**, en ventanas fijas de un minuto, y cubren toda la API
—no sólo las rutas de CFDI—:

| Ruta                                                                                         | Límite      |
| -------------------------------------------------------------------------------------------- | ----------- |
| `POST /cfdi/timbrar`, `/cfdi/timbrar-xml`, `/cfdi/timbrar-sellado`, `/cfdi/complemento-pago` | 300 req/min |
| `GET /cfdi/{id}/xml`, `GET /cfdi/{id}/pdf`                                                   | 300 req/min |
| `POST /cfdi/cancelar`                                                                        | 120 req/min |
| `GET /cfdi/{id}/estatus`                                                                     | 60 req/min  |
| `GET /cfdi`, `GET /cfdi/{id}`, `GET /cfdi/{id}/acuse`                                        | 60 req/min  |
| `/empresas` y `/empresas/{id}` (alta, listado, consulta y actualización)                     | 60 req/min  |
| `/empresas/{empresa_id}/certificados/**` (alta, cambio de contraseña, baja del CSD)          | 30 req/min  |
| Cualquier otra ruta autenticada, hoy `/webhooks*`                                            | 60 req/min  |

El **alta de CSD** es la ruta más restringida a propósito: cada llamada valida
criptográficamente el par `.cer`/`.key` y lo sincroniza, así que cuesta segundos. Con 30/min
un onboarding de 100 empresas termina en menos de cuatro minutos.

### Requests sin credencial

Una request que llega sin API key, con una malformada o con una que no reconocemos se cuenta
**por IP de origen**, en un único cupo compartido entre todas las rutas: **60 req/min**.
Excedido ese cupo recibes `429` en lugar del `401` habitual. Es un cupo aparte del de tu
cuenta: agotarlo no consume nada del límite por ruta.

<Note>
  ¿Necesitas más volumen sostenido (por ejemplo, facturación masiva de cierre de mes)?
  Escríbenos — los límites por cuenta son ajustables por plan.
</Note>

## Headers de control

Toda respuesta de una ruta con límite incluye:

| Header                  | Significado                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `X-RateLimit-Limit`     | Límite de la ventana actual, ya resuelto para **esta** ruta. |
| `X-RateLimit-Remaining` | Requests restantes en la ventana.                            |
| `X-RateLimit-Reset`     | Epoch (segundos) en que inicia la siguiente ventana.         |

Lee el límite de `X-RateLimit-Limit` en lugar de codificar la tabla de arriba: es el número
que la API está aplicando a esa ruta en ese momento.

## Al exceder el límite

Recibes `429` con el formato de error estándar y el header `Retry-After` (segundos):

```json theme={null}
{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Límite de 300 requests/minuto excedido. Intenta nuevamente en 12 segundos"
}
```

Manejo recomendado:

* Respeta `Retry-After` — no reintentes antes.
* Para cargas masivas, regula el gasto con un throttle en tu lado (p. ej. 5 requests por
  segundo para mantenerte bajo 300/min de forma sostenida al timbrar) en lugar de ráfagas +
  reintentos.
* La ventana es fija por minuto: una ráfaga al inicio del minuto puede agotar el cupo del
  minuto completo.
* El límite del alta de CSD (30/min) es el primero que topa un onboarding masivo. Si registras
  empresas y certificados en lote, marca el paso por ahí.

El catálogo completo de errores está en [Errores](/errores).