# Límites y versiones

## Solicitudes por minuto

Cada clave tiene su propio cupo: **120 solicitudes por minuto** (ventana fija de 60 segundos; el courier puede configurarlo). Cada respuesta autenticada lo anuncia con los encabezados de la propuesta IETF *RateLimit header fields*:

| Encabezado | Ejemplo | Significa |
| --- | --- | --- |
| `RateLimit-Limit` | `120` | Solicitudes por ventana. |
| `RateLimit-Remaining` | `87` | Las que te quedan en esta ventana. |
| `RateLimit-Reset` | `23` | Segundos hasta que la ventana se renueva. |
| `RateLimit-Policy` | `120;w=60` | Cupo y largo de la ventana en segundos. |

Al pasarte, la respuesta es `429 RATE_LIMITED` con `Retry-After` (segundos). Un lote de hasta 100 entregas cuenta como **una** solicitud: para cierres de día, preferí el lote.

Los enlaces firmados de comprobantes tienen su propio límite por dirección IP (120 por minuto).

## Tamaños

| Qué | Límite |
| --- | --- |
| Cuerpo de alta o corrección | 8 KiB |
| Cuerpo del lote | 512 KiB y hasta 100 entregas |
| `Idempotency-Key` | 1–128 caracteres `A-Z a-z 0-9 _ . : -` |
| `externalReference` | 1–64 caracteres `A-Z a-z 0-9 _ . : # / -` |
| Página del listado | 1–100 (50 por defecto) |
| Claves activas por empresa | 10 |
| Webhooks por empresa | 5 |
| Entregas de prueba por empresa | 1000 (se borran a los 30 días) |

## Versiones y cambios

- La versión va en la ruta: `/api/v1`. Dentro de `v1` sólo hacemos **cambios aditivos**: campos nuevos en las respuestas, eventos nuevos, parámetros opcionales nuevos. Tu código tiene que ignorar campos y eventos que no conoce.
- Un cambio incompatible (quitar o renombrar un campo, cambiar un tipo o un significado) iría en `/api/v2`, con aviso previo y un período en que conviven las dos versiones.
- Los cambios se anotan en [Cambios](cambios.html).