Rate limits

El API Connect limita el número de peticiones por API key en dos ventanas temporales simultáneas.

Los límites

Ventana	Límite por defecto
Por minuto	120 peticiones
Por hora	5 000 peticiones

Ambas ventanas se evalúan en cada petición. Si cualquiera se excede, el API responde con HTTP 429.

Estos son valores por defecto. Si tu caso de uso requiere volúmenes más altos (emisión masiva batch, reporting intensivo), contacta a Ocote para ajustar los límites de tu key.

Por qué dos ventanas

• La ventana por minuto protege contra spikes accidentales — un loop que se salió de control emitiendo miles de facturas por segundo.
• La ventana por hora protege contra abuso sostenido y garantiza capacidad equitativa entre clientes del API.

Un flujo normal de emisión (una factura cuando un cliente paga) nunca toca ninguna de las dos.

Headers de control

Toda respuesta del API Connect (incluyendo errores) incluye estos headers:

Header	Descripción
X-RateLimit-Limit-Minute	Tu límite por minuto. Ej: 120.
X-RateLimit-Limit-Hour	Tu límite por hora. Ej: 5000.
X-RateLimit-Remaining-Minute	Peticiones disponibles en la ventana actual de 60 s.
X-RateLimit-Remaining-Hour	Peticiones disponibles en la ventana actual de 1 h.
X-RateLimit-Reset	Segundos hasta que la ventana de minuto se resetee.

Ejemplo real:

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit-Minute: 120
X-RateLimit-Limit-Hour: 5000
X-RateLimit-Remaining-Minute: 118
X-RateLimit-Remaining-Hour: 4982
X-RateLimit-Reset: 42

Léelos desde tu cliente para ajustar tu ritmo de emisión. Si Remaining-Minute baja a 10, es buena señal de que necesitas desacelerar.

Cuando excedes el límite

HTTP 429 con header Retry-After indicando segundos:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 18
X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 0
X-RateLimit-Reset: 18

{
  "detail": "Limite de 120 requests por minuto excedido"
}

Regla: espera exactamente Retry-After segundos antes de reintentar. Cualquier petición antes de ese tiempo también recibirá 429.

Python (requests)

def request_with_backoff(method, url, **kwargs):
    for _ in range(5):
        r = requests.request(method, url, **kwargs)
        if r.status_code == 429:
            retry_after = int(r.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            continue
        return r
    raise Exception("Rate limit no cede después de 5 intentos")

Node.js (axios)

async function requestWithBackoff(config) {
  for (let i = 0; i < 5; i++) {
    try {
      return await axios(config);
    } catch (err) {
      if (err.response?.status === 429) {
        const retry = parseInt(err.response.headers['retry-after'] || '60');
        await new Promise(r => setTimeout(r, retry * 1000));
        continue;
      }
      throw err;
    }
  }
  throw new Error('Rate limit no cede después de 5 intentos');
}

Qué cuenta contra el límite

Tipo de respuesta	¿Cuenta contra el límite?
HTTP 200 (éxito, rechazo MH, contingencia)	Sí
HTTP 400 (payload inválido)	Sí
HTTP 401 (API key inválida)	No
HTTP 404 (documento no encontrado)	Sí
HTTP 429 (rate limit)	No
HTTP 500 (error interno Ocote)	Sí

Los 401 no cuentan porque no requieren trabajo del API y no tienen sentido rate-limitear ataques de credential stuffing por esa vía. Los 429 no cuentan porque sería una contradicción.

Las consultas (GET /status/{id}, GET /file/{id}) cuentan igual que las emisiones.

Buenas prácticas

Agrupa polling. Si estás monitoreando N documentos en contingencia, hazlo una vez por hora revisando todos, no cada documento cada minuto. Ver Contingencia > Polling responsable.

No reintentes 429 sin esperar. Un reintento inmediato de 429 no acelera la emisión, solo te mantiene en 429.

Usa Remaining-Minute para desacelerar proactivamente. Si bajas de 10, inserta un sleep(X-RateLimit-Reset + 1) antes de la siguiente petición.

Batch processing: si necesitas emitir 500 facturas de una corrida, envíalas con pausas de ~500 ms entre cada una para mantenerte muy por debajo de 120/minuto. A ese ritmo tardarías 4 minutos para las 500; si intentas ir a máxima velocidad, acabas esperando más por los 429.

Monitorea los headers en producción. Dashboardea X-RateLimit-Remaining-Hour de tus responses para detectar tendencias antes de que revienten.

Límites no-numéricos

Además del rate limit cuantitativo, el API tiene límites cualitativos de payload:

• lines[] por documento: máximo 2 000 líneas.
• Descripción de línea: máximo 1 000 caracteres.
• external_ref: máximo 100 caracteres.
• Longitud total del body JSON: máximo 5 MB.

Estos se enforzan a nivel de validación (HTTP 400), no de rate limit. Exceder cualquiera devuelve un error de payload con detalle específico.

Ver también

• Respuestas y estados — semántica de HTTP codes.
• Retry e idempotencia — cómo reintentar de forma segura (incluye 429).