Errores
Comprende las respuestas de error de la API, los códigos de cierre de WebSocket y cómo manejarlos
Formato de error de la API REST (HTTP)
Cuando ocurre un error en un endpoint HTTP estándar, la API devuelve una respuesta JSON con la siguiente estructura:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Descripción del error legible para humanos",
"details": {
// Contexto adicional (varía según el tipo de error)
}
}
}
Formato de error de WebSocket (WSS)
Los WebSockets manejan los errores de forma diferente. Los errores pueden ocurrir durante el handshake de conexión inicial o a mitad de la transmisión mientras se genera el audio.
- Errores fatales: La conexión se cierra con un código de cierre específico (p. ej., 4290).
- Errores durante la transmisión: El servidor envía una trama de error JSON simple antes de cerrar:
{"error": "Créditos insuficientes durante la transmisión"}
Códigos de estado y códigos de cierre
Códigos de estado HTTP (REST)
| Estado | Significado | Descripción |
|---|---|---|
200 |
Aceptar | La solicitud tuvo éxito |
400 |
Solicitud incorrecta | Parámetros de solicitud no válidos o solicitud mal formada |
401 |
No autorizado | Clave de API faltante o no válida |
402 |
Pago requerido | No hay suficientes créditos para completar la solicitud |
403 |
Prohibido | La clave de API no tiene permiso para esta acción |
404 |
No encontrado | El recurso solicitado no existe |
409 |
Conflicto | La solicitud entra en conflicto con el estado actual (p. ej., solicitud HTTP simultánea) |
429 |
Demasiadas solicitudes | Límite de tasa excedido |
500 |
Error interno del servidor | Algo salió mal de nuestro lado |
Códigos de cierre de WebSocket (WSS)
| Código | Tipo | Descripción |
|---|---|---|
1000 |
Cierre normal | La transmisión se completó correctamente. |
3011 |
Error de generación | Falló la generación de audio en la API de origen. Vuelve a intentar la solicitud. |
4001 |
Falta autenticación | No se proporcionó ninguna clave de API en el encabezado Authorization durante el handshake. |
4002 |
Error de autenticación | Clave no válida, cuenta inactiva, créditos iniciales insuficientes o restricción de IP. |
4290 |
Límite de concurrencia | Ya tienes una conexión WebSocket de TTS activa. El límite es 1 por usuario. |
Escenarios de error comunes
1. No autorizado / Error de autenticación
La autenticación falló debido a una clave de API faltante o inválida, o a restricciones de la lista blanca de IP.
Causas comunes:
- Falta el encabezado Authorization: Bearer
- Formato de clave de API inválido o la clave ha sido revocada
- Conexión desde una dirección IP que no está en la lista blanca de tu clave
2. Créditos insuficientes
Tu cuenta no tiene suficientes créditos para completar esta solicitud.
- HTTP: Falla inmediatamente antes de generar el audio.
- WebSocket: Si te quedas sin créditos a mitad del flujo, el servidor envía
{"error": "Créditos insuficientes durante la transmisión"}y cierra la conexión limpiamente. El audio generado antes de quedarte sin créditos se entregará igualmente.
3. Concurrencia y límites de tasa
Moknah procesa una solicitud por usuario a la vez para garantizar un uso justo.
- HTTP 409: Ya se está procesando otra solicitud de tu cuenta. Espera a que termine.
- HTTP 429: Superaste el límite de 60 solicitudes por minuto (RPM).
- WSS 4290: Intentaste abrir una segunda conexión WebSocket mientras la primera seguía activa.
4. Solicitud inválida / Datos incorrectos
Los parámetros de la solicitud son inválidos o superaste los límites de fragmentos de texto.
- HTTP: Faltan campos obligatorios (text, voice_id).
- WebSocket: Enviar un fragmento de texto de más de 2,000 caracteres provocará
{"error": "Fragmento demasiado grande. Máximo 2000 caracteres por fragmento."}.
Manejo de errores en el código
import requests
import time
def generate_speech(text, voice_id, api_key):
url = "https://moknah.io/api/v1/tts/generate"
headers = {"Authorization": f"Bearer {api_key}"}
response = requests.post(url, json={"text": text, "voice_id": voice_id}, headers=headers)
if response.status_code == 200:
return response.content # Bytes de audio
elif response.status_code == 402:
raise Exception("Créditos insuficientes")
elif response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 5))
time.sleep(retry_after)
return generate_speech(text, voice_id, api_key) # Reintentar
elif response.status_code == 409:
time.sleep(5)
return generate_speech(text, voice_id, api_key) # Reintentar
else:
raise Exception(f"API error: {response.status_code}")
async function generateSpeech(text, voiceId, apiKey) {
const response = await fetch("https://moknah.io/api/v1/tts/generate", {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ text: text, voice_id: voiceId })
});
if (response.ok) return await response.blob();
if (response.status === 429) {
const retryAfter = response.headers.get("Retry-After") || 5;
await new Promise(r => setTimeout(r, retryAfter * 1000));
return generateSpeech(text, voiceId, apiKey);
}
if (response.status === 409) {
await new Promise(r => setTimeout(r, 5000));
return generateSpeech(text, voiceId, apiKey);
}
const error = await response.json();
throw new Error(error.error?.message || "API Error");
}
const ws = new WebSocket('wss://moknah.io/api/v1/api/v1/tts/ws/', {
headers: { "Authorization": `Bearer ${apiKey}` }
});
// Handle Mid-Stream JSON Errors
ws.on('message', (data, isBinary) => {
if (!isBinary) {
const msg = JSON.parse(data.toString());
if (msg.error) {
console.error("Stream Error:", msg.error);
// e.g., "Insufficient credits during stream"
}
}
});
// Handle Fatal Close Codes
ws.on('close', (code, reason) => {
switch(code) {
case 1000:
console.log("Stream finished successfully.");
break;
case 4001:
case 4002:
console.error("Authentication failed. Check your API key.");
break;
case 4290:
console.error("Concurrency limit reached. Close other active streams.");
// Wait a few seconds before attempting to reconnect
setTimeout(reconnect, 5000);
break;
case 3011:
console.error("Upstream generation failed. Please try again.");
break;
default:
console.error(`Disconnected with code ${code}`);
}
});
Para los errores 429 (HTTP), 409 (HTTP) y 4290 (WSS), implementa un retroceso exponencial: espera 1 s, luego 2 s, luego 4 s, etc. Esto evita saturar la API y garantiza que tu solicitud tenga éxito una vez que se libere el bloqueo.
Para preguntas o problemas relacionados con la API, contáctanos en api@moknah.io.