Límites de llamadas API y cuotas — España
Límites token-bucket, comportamiento de ráfaga y manejo de 429 para la REST API Corp-Merch en España.
Arquitectura — Límites por clave y por ruta en España
Cada API key tiene su propio token bucket por ruta. Por defecto: Standard 600 req/min en /v1/orders y /v1/invoices, 1 200 req/min en endpoints de solo lectura; Pro 10x. Ráfagas hasta 2x durante 10 segundos. Respuestas con cabeceras X-RateLimit-Limit, -Remaining, -Reset. La emisión de facturas FACe/SII es asíncrona y no tiene rate-limit en el submit — solo en el polling de estado. El cálculo de IVA 21% es ilimitado.
Cómo integrarlo — Respuestas 429 y Retry-After
Cuando excedes el límite devolvemos 429 Too Many Requests con cabecera Retry-After en segundos. Nuestros SDKs lo gestionan con backoff exponencial y jitter; en clientes custom replica esa lógica y nunca hagas busy-loop. 429 sostenidos > 5 minutos alertan automáticamente a nuestro equipo de CS — preferimos subir tu límite que verte fallar.
Operación y casos límite — Cuotas y uso justo
Además de los rate limits, las cuotas mensuales limitan pedidos, facturas y webhooks por tenant — dimensionadas a tu contrato. Las soft quotas avisan al 80% y 100% por dashboard y email; las hard quotas (raras, solo trial) rechazan con 402 Payment Required. Las lecturas de catálogo y el polling de estado FACe / Suministro Inmediato de Información (SII) son ilimitados en planes de pago.
Preguntas frecuentes
¿Puedo conseguir un límite mayor?
Sí — en Pro y Enterprise ajustamos límites al volumen contratado. Contacta a soporte con un perfil de carga sostenido.
¿Los endpoints de lectura son más ligeros?
Sí — los endpoints read (GET /v1/catalog, GET /v1/orders) tienen 2x el límite de los de escritura por defecto.
¿Y los webhooks?
El throughput webhook va aparte — hasta 50/s por endpoint con backpressure; el inbound no se paga.
¿Gestión de ráfagas?
El token bucket permite 2x burst durante ~10 segundos, luego se aplica steady-state. Útil para jobs de fin de mes.
¿Polling de FACe/SII?
El polling de /v1/invoices/{id} tiene rate-limit como otras lecturas; recomendamos webhooks para la confirmación FACe/SII.