Moknah Документы
Начать бесплатно
Справочник по API

Ошибки

Разбор ответов API с ошибками и кодов закрытия WebSocket: как их обрабатывать

Формат ошибок REST API (HTTP)

При возникновении ошибки на стандартной HTTP-конечной точке API возвращает JSON-ответ со следующей структурой:

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "Понятное человеку описание ошибки",
        "details": {
          // Дополнительный контекст (зависит от типа ошибки)
        }
    }
}

Формат ошибок WebSocket (WSS)

В WebSockets ошибки обрабатываются иначе. Они могут возникать как во время первоначального рукопожатия при установке соединения, так и в процессе передачи данных, когда генерируется аудио.

  • Критические ошибки: Соединение разрывается с определенным кодом закрытия (например, 4290).
  • Ошибки в процессе выполнения: Перед закрытием соединения сервер отправляет плоский JSON-кадр с информацией об ошибке: {"error": "Недостаточно кредитов во время трансляции"}

Коды состояния и коды закрытия

Коды состояния HTTP (REST)

Статус Значение Описание
200 Хорошо Запрос выполнен успешно
400 Неверный запрос Некорректные параметры запроса или неправильно сформированный запрос
401 Несанкционированный Отсутствует или недействителен API-ключ
402 Требуется оплата Недостаточно кредитов для выполнения запроса
403 Запрещено У API-ключа нет прав на выполнение этого действия.
404 Не найдено Запрошенный ресурс не существует
409 Конфликт Запрос конфликтует с текущим состоянием (например, одновременный HTTP-запрос)
429 Слишком много запросов Превышен лимит запросов
500 Внутренняя ошибка сервера Что-то пошло не так с нашей стороны

Коды закрытия WebSocket (WSS)

Код Тип Описание
1000 Нормальное завершение Поток успешно завершен.
3011 Ошибка генерации Сбой генерации аудио в вышестоящем API. Повторите запрос.
4001 Отсутствуют данные авторизации В заголовке Authorization во время рукопожатия не был передан API-ключ.
4002 Ошибка аутентификации Неверный ключ, неактивная учетная запись, недостаточно начальных кредитов или ограничение по IP.
4290 Лимит на количество одновременных операций У вас уже есть активное WebSocket-соединение для TTS. Ограничение — 1 соединение на пользователя.

Типичные сценарии возникновения ошибок

1. Неавторизованный доступ / Ошибка аутентификации

HTTP: 401 WSS: 4001 / 4002

Ошибка аутентификации: отсутствует или недействителен API-ключ, либо сработали ограничения списка разрешенных IP-адресов.

Распространенные причины:

  • Отсутствует заголовок Authorization: Bearer
  • Неверный формат API-ключа или ключ был отозван
  • Подключение с IP-адреса, не входящего в белый список вашего ключа

2. Недостаточно кредитов

HTTP: 402 WSS: JSON в потоке

На вашем счете недостаточно кредитов для выполнения этого запроса.

  • HTTP: Сбой происходит непосредственно перед генерацией аудио.
  • WebSocket: Если кредиты закончатся во время потоковой передачи, сервер отправляет {"error": "Недостаточно кредитов во время трансляции"} и корректно закрывает соединение. Аудио, сгенерированное до исчерпания кредитов, будет доставлено.

3. Параллелизм и ограничения частоты запросов

HTTP: 409 / 429 WSS: 4290

Moknah обрабатывает по одному запросу от каждого пользователя одновременно, чтобы обеспечить справедливое использование.

  • HTTP 409: Другой запрос от вашего аккаунта уже обрабатывается. Дождитесь его завершения.
  • HTTP 429: Вы превысили лимит в 60 запросов в минуту (RPM).
  • WSS 4290: Вы попытались открыть второе WebSocket-соединение, в то время как первое всё ещё было активно.

4. Некорректный запрос / Неверные данные

HTTP: 400 WSS: JSON в потоке

Параметры запроса недопустимы, или вы превысили ограничения на размер фрагмента текста.

  • HTTP: Отсутствуют обязательные поля (text, voice_id).
  • WebSocket: Отправка фрагмента текста объемом более 2000 символов приведет к {"error": "Фрагмент слишком велик. Максимум 2000 символов на фрагмент."}.

Обработка ошибок в коде

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  # Аудиофрагменты
    elif response.status_code == 402:
        raise Exception("Недостаточно кредитов")
    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)  # Повторить попытку
    elif response.status_code == 409:
        time.sleep(5)
        return generate_speech(text, voice_id, api_key)  # Повторить попытку
    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}`);
    }
});
Рекомендуемая практика: экспоненциальная задержка

При возникновении ошибок 429 (HTTP), 409 (HTTP) и 4290 (WSS) используйте стратегию экспоненциальной задержки: подождите 1 с, затем 2 с, 4 с и так далее. Это предотвратит перегрузку API и гарантирует успешное выполнение запроса после снятия блокировки.

Поддержка API

По вопросам или проблемам, связанным с API, обращайтесь к нам по адресу api@moknah.io.