Moknah Dokumentacja
Zacznij za darmo
Dokumentacja API

Błędy

Zrozumienie odpowiedzi błędów API, kodów zamknięcia WebSocket oraz sposobów ich obsługi

Format błędu REST API (HTTP)

Gdy wystąpi błąd w standardowym punkcie końcowym HTTP, API zwraca odpowiedź JSON o następującej strukturze:

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "Czytelny dla człowieka opis błędu",
        "details": {
          // Dodatkowy kontekst (różni się w zależności od typu błędu)
        }
    }
}

Format błędu WebSocket (WSS)

WebSockety obsługują błędy w inny sposób. Błędy mogą wystąpić podczas początkowego nawiązywania połączenia (handshake) lub w trakcie transmisji podczas generowania dźwięku.

  • Błędy krytyczne: Połączenie zostaje przerwane z określonym kodem zamknięcia (np. 4290).
  • Błędy w trakcie transmisji: Przed zamknięciem serwer wysyła prostą ramkę błędu JSON: {"error": "Niewystarczająca liczba kredytów podczas transmisji"}

Kody stanu i kody zamknięcia

Kody stanu HTTP (REST)

Status Znaczenie Opis
200 OK Żądanie powiodło się
400 Nieprawidłowe żądanie Nieprawidłowe parametry żądania lub błędnie sformułowane żądanie
401 Brak autoryzacji Brakujący lub nieprawidłowy klucz API
402 Wymagana płatność Niewystarczająca liczba kredytów do zrealizowania żądania
403 Zabronione Klucz API nie ma uprawnień do wykonania tej czynności
404 Nie znaleziono Żądany zasób nie istnieje
409 Konflikt Żądanie koliduje z bieżącym stanem (np. jednoczesne żądanie HTTP)
429 Zbyt wiele żądań Przekroczono limit zapytań
500 Wewnętrzny błąd serwera Coś poszło nie tak po naszej stronie

Kody zamknięcia WebSocket (WSS)

Kod Typ Opis
1000 Normalne zamknięcie Transmisja zakończona pomyślnie.
3011 Błąd generowania Generowanie dźwięku w nadrzędnym API nie powiodło się. Ponów żądanie.
4001 Brak uwierzytelnienia Podczas nawiązywania połączenia (handshake) nie podano klucza API w nagłówku Authorization.
4002 Błąd uwierzytelniania Nieprawidłowy klucz, nieaktywne konto, niewystarczająca początkowa liczba kredytów lub ograniczenie IP.
4290 Limit jednoczesnych połączeń Masz już aktywne połączenie WebSocket TTS. Limit wynosi 1 na użytkownika.

Typowe scenariusze błędów

1. Brak autoryzacji / Błąd uwierzytelniania

HTTP: 401 WSS: 4001 / 4002

Uwierzytelnianie nie powiodło się z powodu brakującego lub nieprawidłowego klucza API albo ograniczeń białej listy adresów IP.

Częste przyczyny:

  • Brak nagłówka Authorization: Bearer
  • Nieprawidłowy format klucza API lub klucz został unieważniony
  • Połączenie z adresu IP spoza białej listy przypisanej do klucza

2. Niewystarczająca liczba kredytów

HTTP: 402 WSS: JSON w trakcie strumienia

Na Twoim koncie nie ma wystarczającej liczby kredytów, aby zrealizować to żądanie.

  • HTTP: Kończy się niepowodzeniem tuż przed wygenerowaniem dźwięku.
  • WebSocket: Jeśli kredyty wyczerpią się w trakcie strumieniowania, serwer wysyła {"error": "Niewystarczająca liczba kredytów podczas transmisji"} i prawidłowo zamyka połączenie. Dźwięk wygenerowany przed wyczerpaniem kredytów zostanie mimo to dostarczony.

3. Współbieżność i limity zapytań

HTTP: 409 / 429 WSS: 4290

Moknah przetwarza jedno żądanie na użytkownika naraz, aby zapewnić uczciwe korzystanie z usługi.

  • HTTP 409: Inne żądanie z Twojego konta jest już przetwarzane. Poczekaj na jego zakończenie.
  • HTTP 429: Przekroczono limit 60 żądań na minutę (RPM).
  • WSS 4290: Podjęto próbę otwarcia drugiego połączenia WebSocket, gdy pierwsze było nadal aktywne.

4. Nieprawidłowe żądanie / Błędne dane

HTTP: 400 WSS: JSON w trakcie strumienia

Parametry żądania są nieprawidłowe lub przekroczono limit długości fragmentu tekstu.

  • HTTP: Brak wymaganych pól (text, voice_id).
  • WebSocket: Wysłanie fragmentu tekstu dłuższego niż 2000 znaków spowoduje błąd {"error": "Fragment jest za duży. Maksymalnie 2000 znaków na fragment."}.

Obsługa błędów w kodzie

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  # Bajty audio
    elif response.status_code == 402:
        raise Exception("Niewystarczająca liczba kredytów")
    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)  # Ponów
    elif response.status_code == 409:
        time.sleep(5)
        return generate_speech(text, voice_id, api_key)  # Ponów
    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}`);
    }
});
Dobra praktyka: wykładniczy czas odczekania (Exponential Backoff)

W przypadku błędów 429 (HTTP), 409 (HTTP) i 4290 (WSS) zastosuj wykładniczy czas odczekania (exponential backoff): odczekaj 1 s, następnie 2 s, 4 s itd. Zapobiega to przeciążeniu API i gwarantuje, że żądanie powiedzie się po zwolnieniu blokady.

Wsparcie API

W razie pytań lub problemów związanych z API skontaktuj się z nami pod adresem api@moknah.io.