Moknah Documentación
Empieza gratis
Referencia de la API

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

HTTP: 401 WSS: 4001 / 4002

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

HTTP: 402 WSS: JSON a mitad del flujo

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

HTTP: 409 / 429 WSS: 4290

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

HTTP: 400 WSS: JSON a mitad del flujo

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}`);
    }
});
Buena práctica: retroceso exponencial

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.

Soporte de API

Para preguntas o problemas relacionados con la API, contáctanos en api@moknah.io.