Rate limiting

OrderFast limita la cantidad de requests que puede hacer cada credencial Bearer. En v2 existen límites adicionales para operaciones batch, diseñadas para proteger sync de catálogo, stock y exportaciones masivas.

Los límites se aplican por credencial, no por IP ni por endpoint individual.

Límites de requests

Cada credencial puede tener dos límites de requests HTTP:

Límite	Ventana	Qué controla
Por minuto	60 segundos	Picos de tráfico en tiempo real
Mensual	Calendario mensual	Volumen total de requests del período

Si superás cualquiera de los dos, la API responde con 429 Too Many Requests.

Headers de requests

Toda respuesta exitosa incluye:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 185
X-RateLimit-Reset: 1783420800

Header	Descripción
X-RateLimit-Limit	Máximo de requests permitidos en la ventana actual
X-RateLimit-Remaining	Requests que te quedan antes de alcanzar el límite
X-RateLimit-Reset	Timestamp Unix (segundos) en que se reinicia la ventana

Límites de tu credencial

Los valores de requests por minuto y mensuales dependen de tu credencial. Consultalos con el equipo de OrderFast o revisá los headers en cada respuesta.

Límites batch (v2)

Las operaciones batch tienen un cupo separado del límite de requests regulares. Aplica a endpoints que procesan lotes de datos, como:

• POST /v2/catalog/sync
• POST /v2/sync/products
• POST /v2/stock/sync
• GET /v2/orders/export

Parámetros de límite batch

Parámetro	Descripción
batch_jobs_per_hour	Cantidad máxima de jobs batch que podés iniciar por hora
max_items_per_batch	Cantidad máxima de ítems por request batch

Headers batch

En operaciones batch, además de los headers estándar, recibirás:

X-RateLimit-Batch-Limit: 30
X-RateLimit-Batch-Remaining: 28
X-RateLimit-Batch-Reset: 1783424400

Header	Descripción
X-RateLimit-Batch-Limit	Máximo de jobs batch permitidos en la ventana
X-RateLimit-Batch-Remaining	Jobs batch que te quedan
X-RateLimit-Batch-Reset	Timestamp Unix en que se reinicia el cupo batch

Valores por defecto

Si tu credencial no define límites batch propios, la plataforma aplica estos valores:

Parámetro	Default
batch_jobs_per_hour	30
max_items_per_batch	500

Si necesitás procesar volúmenes mayores, contactá al equipo de OrderFast para ajustar los límites de tu credencial.

Qué hacer cuando recibís un 429

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please retry later.",
    "request_id": "req_01J..."
  }
}

Pasos recomendados:

1. Identificá qué límite alcanzaste — revisá si fue el cupo de requests (X-RateLimit-*) o el batch (X-RateLimit-Batch-*).
2. Esperá hasta el reset correspondiente — usá X-RateLimit-Reset o X-RateLimit-Batch-Reset.
3. No reintentar en loop — aplicá backoff exponencial si no tenés el header de reset.
4. Para sync jobs, consultá el estado del job con GET /v2/sync/jobs/:id en lugar de crear jobs duplicados.

Buenas prácticas para ERP

• Respetá max_items_per_batch — dividí lotes grandes en chunks de hasta 500 ítems.
• Un job a la vez — esperá a que un sync termine antes de lanzar otro del mismo tipo.
• Usá GET /v2/catalog para lecturas completas en lugar de múltiples requests por recurso.
• Preferí sync batch sobre cientos de POST/PATCH individuales al sincronizar catálogo.
• Monitoreá ambos sets de headers — requests y batch son independientes y podés agotar uno sin agotar el otro.

Relacionado

• Sync jobs — cómo crear y consultar jobs batch
• Errores — formato completo de errores, incluido rate_limited
• Autenticación — validación de credencial, permisos y rate limits