Límites de uso
Comprende los límites de tasa de la API, la concurrencia y cómo trabajar con ellos
Resumen
Los límites de tasa protegen la API contra abusos y garantizan un uso justo para todos los usuarios. Moknah aplica límites en la frecuencia de solicitudes, el consumo de créditos y las conexiones simultáneas tanto en nuestros endpoints HTTP como WebSocket.
Moknah procesa exactamente una acción por usuario a la vez.
• HTTP: Espera a que se complete la solicitud actual antes de enviar otra. Las solicitudes simultáneas reciben un error 409 Conflict o 429 Too Many Requests.
• WebSocket: Solo puedes tener 1 conexión WebSocket activa a la vez. Si abres una segunda conexión, se cerrará al instante con el código 4290.
Límites predeterminados
| Tipo de límite | Valor | Se aplica a | Descripción |
|---|---|---|---|
| Solicitudes por minuto (RPM) | 60 |
Solo HTTP | Número máximo de solicitudes POST estándar de la API por minuto. |
| Créditos por minuto (CPM) | 10,000 |
HTTP y WebSocket | Máximo de créditos consumidos por minuto. |
| Conexiones activas | 1 |
Solo WebSocket | Número máximo de transmisiones WSS simultáneas por usuario. |
Límites y códigos de cierre de WebSocket
Dado que los WebSockets mantienen una conexión persistente, no usan encabezados HTTP para limitar las solicitudes. En su lugar, los límites se aplican mediante cierres de conexión y mensajes de control JSON:
| Límite alcanzado | Comportamiento / Salida |
|---|---|
| Límite de concurrencia | La conexión se cierra al instante con el código 4290. |
| Créditos agotados | Recibe un error JSON y se cierra. |
| Límite de tamaño de fragmento | Recibe un error JSON si un solo fragmento de texto supera los 2,000 caracteres. |
| Límite de frecuencia de mensajes | Recibe un error JSON si envías fragmentos de texto más rápido de lo que la cola puede procesarlos. |
Nota: Si tu WebSocket se desconecta inesperadamente, espera al menos 15 segundos antes de reconectar para asegurarte de que el bloqueo del servidor se haya liberado por completo.
Encabezados HTTP de límite de solicitudes
Para los endpoints REST estándar, cada respuesta de la API incluye encabezados que te ayudan a monitorear tu estado:
| Encabezado | Descripción | Ejemplo |
|---|---|---|
RateLimit-Limit |
Tu límite de solicitudes por minuto (RPM) | 60 |
RateLimit-Remaining |
Solicitudes restantes en este minuto | 45 |
RateLimit-Reset |
Marca de tiempo Unix cuando se restablecen los límites | 1699574460 |
Moknah-Credits-Remaining |
Créditos restantes en este minuto | 10000 |
Moknah-Credits-Used |
Créditos usados en este minuto | 5000 |
Cuando se alcanza el límite de solicitudes HTTP
Si superas el límite de solicitudes HTTP, recibirás una respuesta 429 Too Many Requests con estos encabezados adicionales:
| Encabezado | Descripción | Ejemplo |
|---|---|---|
Retry-After |
Segundos de espera antes de reintentar | 45 |
RateLimit-Reset |
Marca de tiempo Unix cuando puedes reintentar | 1699574460 |
Cálculo de créditos
Los créditos se calculan según la longitud del texto y las opciones de procesamiento. Para WebSockets, los créditos se descuentan dinámicamente por fragmento a medida que se transmiten.
| Factor | Multiplicador | Descripción |
|---|---|---|
| Costo base | 1x |
1 créditos por carácter |
| Normalización mejorada con IA | 2x |
Procesamiento avanzado de árabe con signos diacríticos |
| Voz Premium | +% |
Porcentaje adicional para voces premium |
Ejemplo: Un texto de 500 caracteres con normalización mejorada por IA:
500 characters × 2 (AI-Enhanced) = 1,000 credits
Mejores prácticas
1. Usa WebSockets para texto secuencial de gran volumen
Si estás generando respuestas de IA conversacional o procesando documentos largos, no hagas 50 solicitudes HTTP POST rápidas. Abre una única conexión WebSocket y transmite los fragmentos a través de la conexión persistente. Esto evita por completo el límite HTTP de 60 RPM (aunque los límites de créditos siguen aplicando).
2. Implementa una cola de solicitudes (HTTP)
Como Moknah no admite solicitudes simultáneas, pon tus solicitudes HTTP en cola y procésalas de forma secuencial:
import queue
import threading
import time
class TTSQueue:
def __init__(self, api_key):
self.api_key = api_key
self.queue = queue.Queue()
self.worker = threading.Thread(target=self._process_queue, daemon=True)
self.worker.start()
def _process_queue(self):
while True:
text, voice_id, callback = self.queue.get()
try:
result = self._generate(text, voice_id)
callback(result, None)
except Exception as e:
callback(None, e)
finally:
self.queue.task_done()
def _generate(self, text, voice_id):
# Your API call here
pass
def add(self, text, voice_id, callback):
self.queue.put((text, voice_id, callback))
# Usage
tts = TTSQueue("your_api_key")
tts.add("Hello world", "voice_123", lambda r, e: print(r or e))
class TTSQueue {
constructor(apiKey) {
this.apiKey = apiKey;
this.queue = [];
this.processing = false;
}
async add(text, voiceId) {
return new Promise((resolve, reject) => {
this.queue.push({ text, voiceId, resolve, reject });
this.processNext();
});
}
async processNext() {
if (this.processing || this.queue.length === 0) return;
this.processing = true;
const { text, voiceId, resolve, reject } = this.queue.shift();
try {
const result = await this.generate(text, voiceId);
resolve(result);
} catch (error) {
reject(error);
} finally {
this.processing = false;
this.processNext(); // Process next in queue
}
}
async generate(text, voiceId) {
// Your API call here
}
}
// Usage
const tts = new TTSQueue("your_api_key");
const audio = await tts.add("Hello world", "voice_123");
2. Implementa una cola de solicitudes (HTTP)
Como Moknah no admite solicitudes simultáneas, pon tus solicitudes HTTP en cola y procésalas de forma secuencial:
import time
import random
def request_with_backoff(func, max_retries=5):
retries = 0
while retries < max_retries:
try:
response = func()
if response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 60))
# Add jitter to prevent thundering herd
wait_time = retry_after + random.uniform(0, 1)
print(f"Rate limited. Waiting {wait_time:.1f}s...")
time.sleep(wait_time)
retries += 1
continue
return response
except Exception as e:
# Exponential backoff for other errors
wait_time = (2 ** retries) + random.uniform(0, 1)
print(f"Error: {e}. Retrying in {wait_time:.1f}s...")
time.sleep(wait_time)
retries += 1
raise Exception("Max retries exceeded")
async function requestWithBackoff(func, maxRetries = 5) {
let retries = 0;
while (retries < maxRetries) {
try {
const response = await func();
if (response.status === 429) {
const retryAfter = parseInt(response.headers.get("Retry-After") || 60);
// Add jitter to prevent thundering herd
const waitTime = retryAfter + Math.random();
console.log(`Rate limited. Waiting ${waitTime.toFixed(1)}s...`);
await new Promise(r => setTimeout(r, waitTime * 1000));
retries++;
continue;
}
return response;
} catch (error) {
// Exponential backoff for other errors
const waitTime = Math.pow(2, retries) + Math.random();
console.log(`Error: ${error.message}. Retrying in ${waitTime.toFixed(1)}s...`);
await new Promise(r => setTimeout(r, waitTime * 1000));
retries++;
}
}
throw new Error("Max retries exceeded");
}
3. Implementa el retroceso exponencial
Cuando alcances el límite de tasa (HTTP 429) o el límite de conexiones (WebSocket 4290), usa retroceso exponencial para reintentar de forma segura sin saturar el servidor:
Resumen
Límites de HTTP: 60 RPM, 1 solicitud simultánea.
Límites de WebSocket: 1 conexión simultánea, 2,000 caracteres por fragmento.
Límites globales: 10,000 CPM (créditos por minuto).
¿Necesitas más capacidad? Correo electrónico sales@moknah.io
Para preguntas o problemas relacionados con la API, contáctanos en api@moknah.io.