Moknah Doku
Kostenlos starten
API-Referenz

Fehler

API-Fehlerantworten, WebSocket-Schließcodes und deren Handhabung verstehen

REST-API-Fehlerformat (HTTP)

Wenn bei einem Standard-HTTP-Endpunkt ein Fehler auftritt, gibt die API eine JSON-Antwort mit folgender Struktur zurück:

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "Menschenlesbare Fehlerbeschreibung",
        "details": {
          // Zusätzlicher Kontext (variiert je nach Fehlertyp)
        }
    }
}

WebSocket-Fehlerformat (WSS)

WebSockets behandeln Fehler anders. Fehler können beim initialen Verbindungsaufbau (Handshake) oder mitten im Stream während der Audiogenerierung auftreten.

  • Schwerwiegende Fehler: Die Verbindung wird mit einem bestimmten Schließcode abgebrochen (z. B. 4290).
  • Fehler während des Streams: Der Server sendet vor dem Schließen einen flachen JSON-Fehler-Frame: {"error": "Unzureichende Credits während des Streams"}

Statuscodes & Schließcodes

HTTP-Statuscodes (REST)

Status Bedeutung Beschreibung
200 OK Anfrage erfolgreich
400 Ungültige Anfrage Ungültige Anfrageparameter oder fehlerhafte Anfrage
401 Nicht autorisiert Fehlender oder ungültiger API-Schlüssel
402 Zahlung erforderlich Nicht genügend Credits, um die Anfrage abzuschließen
403 Verboten Der API-Schlüssel hat keine Berechtigung für diese Aktion
404 Nicht gefunden Die angeforderte Ressource existiert nicht
409 Konflikt Anfrage steht im Konflikt mit dem aktuellen Status (z. B. gleichzeitige HTTP-Anfrage)
429 Zu viele Anfragen Ratenbegrenzung überschritten
500 Interner Serverfehler Auf unserer Seite ist ein Fehler aufgetreten

WebSocket-Schließcodes (WSS)

Code Typ Beschreibung
1000 Normale Schließung Stream erfolgreich abgeschlossen.
3011 Generierungsfehler Audiogenerierung bei der Upstream-API fehlgeschlagen. Wiederholen Sie die Anfrage.
4001 Fehlende Authentifizierung Kein API-Schlüssel im Authorization-Header während des Handshakes angegeben.
4002 Authentifizierung fehlgeschlagen Ungültiger Schlüssel, inaktives Konto, unzureichende Start-Credits oder IP-Beschränkung.
4290 Gleichzeitigkeitslimit Sie haben bereits eine aktive TTS-WebSocket-Verbindung. Das Limit liegt bei 1 pro Benutzer.

Häufige Fehlerszenarien

1. Nicht autorisiert / Authentifizierung fehlgeschlagen

HTTP: 401 WSS: 4001 / 4002

Die Authentifizierung ist aufgrund eines fehlenden oder ungültigen API-Schlüssels oder einer IP-Whitelist-Beschränkung fehlgeschlagen.

Häufige Ursachen:

  • Fehlender Authorization: Bearer-Header
  • Ungültiges API-Schlüsselformat oder Schlüssel wurde widerrufen
  • Verbindung von einer IP-Adresse, die nicht auf der Whitelist Ihres Schlüssels steht

2. Unzureichende Credits

HTTP: 402 WSS: Mid-Stream-JSON

Ihr Konto verfügt nicht über genügend Credits, um diese Anfrage abzuschließen.

  • HTTP: Schlägt sofort vor der Audiogenerierung fehl.
  • WebSocket: Wenn Ihre Credits während des Streams aufgebraucht sind, sendet der Server {"error": "Unzureichende Credits während des Streams"} und schließt die Verbindung ordnungsgemäß. Audio, das vor dem Aufbrauchen der Credits generiert wurde, wird dennoch ausgeliefert.

3. Gleichzeitigkeit & Ratenbegrenzungen

HTTP: 409 / 429 WSS: 4290

Moknah verarbeitet jeweils nur eine Anfrage pro Benutzer, um eine faire Nutzung zu gewährleisten.

  • HTTP 409: Eine andere Anfrage Ihres Kontos wird bereits verarbeitet. Warten Sie, bis diese abgeschlossen ist.
  • HTTP 429: Sie haben das Limit von 60 Anfragen pro Minute (RPM) überschritten.
  • WSS 4290: Sie haben versucht, eine zweite WebSocket-Verbindung zu öffnen, während Ihre erste noch aktiv war.

4. Ungültige Anfrage / Fehlerhafte Daten

HTTP: 400 WSS: Mid-Stream-JSON

Die Anfrageparameter sind ungültig oder Sie haben das Limit für Textabschnitte überschritten.

  • HTTP: Pflichtfelder fehlen (text, voice_id).
  • WebSocket: Das Senden eines Textabschnitts mit mehr als 2.000 Zeichen führt zu {"error": "Abschnitt zu groß. Maximal 2000 Zeichen pro Abschnitt."}.

Fehlerbehandlung im Code

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  # Audio-Bytes
    elif response.status_code == 402:
        raise Exception("Unzureichende Credits")
    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)  # Erneut versuchen
    elif response.status_code == 409:
        time.sleep(5)
        return generate_speech(text, voice_id, api_key)  # Erneut versuchen
    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}`);
    }
});
Best Practice: Exponentielles Backoff

Implementieren Sie für die Fehler 429 (HTTP), 409 (HTTP) und 4290 (WSS) ein exponentielles Backoff: Warten Sie 1 Sek., dann 2 Sek., dann 4 Sek. usw. Dies verhindert eine Überlastung der API und stellt sicher, dass Ihre Anfrage erfolgreich ist, sobald die Sperre aufgehoben wird.

API-Support

Bei Fragen oder Problemen rund um die API kontaktieren Sie uns unter api@moknah.io.