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
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
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
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
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}`);
}
});
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.
Bei Fragen oder Problemen rund um die API kontaktieren Sie uns unter api@moknah.io.