Referencia
Límites de tasa
Los límites protegen la API de las avalanchas, no de los revendedores normales. Cada cuenta tiene un límite por minuto que crece con su gasto, y unos pocos límites estrechos cubren las acciones pesadas. Las reglas propias de un pedido, como la espera de la reposición, devuelven su propio código de error en lugar de un 429.
Capas de límites de tasa
Por IP
20.000 solicitudes / minuto / dirección IP
Se aplica antes de validar la clave, de modo que la enumeración de claves por fuerza bruta queda acotada. Se comparte entre todas las claves detrás de la misma IP. El valor por defecto se establece globalmente y no es configurable por el usuario.
Ventana compartida de la cuenta
120–2.400 solicitudes / 60 segundos móviles
Todas las claves API activas de una cuenta consumen el mismo contador. La escala fija de gasto exitoso acumulado proporciona el límite, salvo que exista una anulación directa de RPM.
Específico por acción
Depende de la acción
Services, catalog, cancel, refill y las acciones de webhook tienen sus propios límites estrechos, que se muestran abajo. Se suman al límite de la cuenta; no lo reemplazan.
Límites por acción
Estos límites cuentan por cuenta y por minuto. Un 429 de uno de ellos informa action en X-RateLimit-DeniedBy. Cancel y refill cuentan ID de pedido, no solicitudes, así que una llamada para 10 pedidos usa 10 de los ID que tienes por minuto. Un cancel o refill con más ID que eso, hasta 100, se acepta si es tu primera llamada del minuto y usa el minuto completo.
| Acción | Por minuto | Qué se cuenta |
|---|---|---|
| services | 10 | Solicitudes |
| catalog | 30 | Solicitudes |
| cancel | 30 | ID de pedido |
| refill | 30 | ID de pedido |
| webhook.* | 10 | Solicitudes |
Escala de gasto exitoso acumulado
El límite de tu cuenta sigue tu gasto exitoso acumulado de por vida; un nivel superior desbloquea al instante un límite mayor. El techo por IP de 20.000 solicitudes por minuto se aplica antes de comprobar la clave. Un administrador puede fijar un límite directo para una cuenta, de hasta 10.000. El nivel de tu cuenta aparece en la cabecera X-RateLimit-Tier y en tu página de API.
| Nivel | Gasto acumulado mínimo | Solicitudes / minuto |
|---|---|---|
| 0 | 0 $ | 120 |
| 1 | 10 $ | 300 |
| 2 | 50 $ | 600 |
| 3 | 100 $ | 900 |
| 4 | 500 $ | 1200 |
| 5 | 1000 $ | 1800 |
| 6 | 2500 $ | 2400 |
Cabeceras de respuesta
Cabeceras de respuesta
X-RateLimit-Limit- En respuestas normales, el límite efectivo de solicitudes por minuto compartido por la cuenta. En un 429, el límite informado por la capa que rechazó.
X-RateLimit-Remaining- En respuestas normales, las solicitudes restantes en la ventana compartida de la cuenta. En un 429, el valor restante informado por la capa que rechazó.
X-RateLimit-Reset- Número relativo de segundos hasta que se reinicie la ventana informada; no es una marca de tiempo Unix.
X-RateLimit-Tier- El nivel ganado por gasto exitoso acumulado (0–6). Una anulación personalizada de RPM no cambia este valor.
X-RateLimit-DeniedBy- Se envía en respuestas 429 cuando rechaza un limitador identificado: "ip", "api_requests_per_minute" o "action".
Retry-After- En un 429 o 503 reintentable, espera al menos los segundos indicados por Retry-After antes de reintentar. Para action=add, reutiliza la misma clave de idempotencia después de esperar.
Cómo manejar respuestas 429
Espera según Retry-After cuando esté presente.
Si no, espera los segundos de X-RateLimit-Reset. Ambos valores son retardos relativos, no horas del reloj; añade variación aleatoria antes de reintentar.Lee X-RateLimit-DeniedBy.
Indica el límite que rechazó la llamada. Cambiar de clave no ayuda, porque los límites de cuenta, IP y acción se comparten.Usa webhooks en lugar de sondear.
Los webhooks llegan al menos una vez, así que haz tu manejador idempotente y usaaction=statuspara comprobar lo importante.Agrupa cuando puedas.
Status, cancel y refill aceptan hasta 100 ID en una solicitud; el recuento de ID de pedido sigue aplicándose a cancel y refill.