Fouten
Inzicht in API-foutmeldingen, WebSocket-sluitingscodes en hoe je deze afhandelt
Foutindeling REST API (HTTP)
Wanneer er een fout optreedt op een standaard HTTP-eindpunt, retourneert de API een JSON-antwoord met de volgende structuur:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Leesbare foutbeschrijving",
"details": {
// Aanvullende context (verschilt per fouttype)
}
}
}
WebSocket-foutindeling (WSS)
WebSockets gaan anders om met fouten. Fouten kunnen optreden tijdens de initiële verbindings-handshake of halverwege de stream terwijl de audio wordt gegenereerd.
- Fatale fouten: De verbinding wordt verbroken met een specifieke sluitcode (bijv. 4290).
- Fouten tijdens de stream: De server stuurt een plat JSON-foutframe voordat de verbinding wordt gesloten:
{"error": "Onvoldoende credits tijdens stream"}
Statuscodes en sluitcodes
HTTP-statuscodes (REST)
| Status | Betekenis | Beschrijving |
|---|---|---|
200 |
OK | Verzoek geslaagd |
400 |
Ongeldig verzoek | Ongeldige verzoekparameters of onjuist gevormd verzoek |
401 |
Niet geautoriseerd | Ontbrekende of ongeldige API-sleutel |
402 |
Betaling vereist | Niet genoeg credits om het verzoek te voltooien |
403 |
Verboden | API-sleutel heeft geen toestemming voor deze actie |
404 |
Niet gevonden | De opgevraagde bron bestaat niet |
409 |
Conflict | Verzoek conflicteert met de huidige status (bijv. gelijktijdig HTTP-verzoek) |
429 |
Te veel verzoeken | Snelheidslimiet overschreden |
500 |
Interne serverfout | Er is iets misgegaan aan onze kant |
WebSocket-sluitcodes (WSS)
| Code | Type | Beschrijving |
|---|---|---|
1000 |
Normale sluiting | Stream succesvol voltooid. |
3011 |
Generatiefout | Audiogeneratie mislukt op de upstream-API. Probeer het verzoek opnieuw. |
4001 |
Authenticatie ontbreekt | Geen API-sleutel opgegeven in de Authorization-header tijdens de handshake. |
4002 |
Authenticatie mislukt | Ongeldige sleutel, inactief account, onvoldoende initiële credits of IP-beperking. |
4290 |
Gelijktijdigheidslimiet | Je hebt al een actieve TTS WebSocket-verbinding. De limiet is 1 per gebruiker. |
Veelvoorkomende foutscenario's
1. Niet geautoriseerd / Authenticatie mislukt
Authenticatie mislukt vanwege een ontbrekende of ongeldige API-sleutel of IP-whitelistbeperkingen.
Veelvoorkomende oorzaken:
- Ontbrekende Authorization: Bearer-header
- Ongeldige indeling van API-sleutel of sleutel is ingetrokken
- Verbinding vanaf een IP-adres dat niet op de whitelist van je sleutel staat
2. Onvoldoende credits
Je account heeft niet genoeg credits om dit verzoek te voltooien.
- HTTP: Mislukt direct vóór het genereren van audio.
- WebSocket: Als je credits halverwege de stream opraken, stuurt de server
{"error": "Onvoldoende credits tijdens stream"}en sluit de verbinding netjes af. Audio die is gegenereerd voordat de credits opraakten, wordt nog steeds geleverd.
3. Gelijktijdigheid en snelheidslimieten
Moknah verwerkt één verzoek per gebruiker tegelijk om eerlijk gebruik te garanderen.
- HTTP 409: Er wordt al een ander verzoek van je account verwerkt. Wacht tot dit is voltooid.
- HTTP 429: Je hebt de limiet van 60 verzoeken per minuut (RPM) overschreden.
- WSS 4290: Je probeerde een tweede WebSocket-verbinding te openen terwijl de eerste nog actief was.
4. Ongeldig verzoek / Foutieve gegevens
De verzoekparameters zijn ongeldig of je hebt de limieten voor tekstblokken overschreden.
- HTTP: Verplichte velden ontbreken (text, voice_id).
- WebSocket: Het verzenden van een tekstblok van meer dan 2.000 tekens resulteert in
{"error": "Tekstblok te groot. Maximaal 2000 tekens per blok."}.
Fouten afhandelen in 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 # Audiobytes
elif response.status_code == 402:
raise Exception("Onvoldoende 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) # Opnieuw proberen
elif response.status_code == 409:
time.sleep(5)
return generate_speech(text, voice_id, api_key) # Opnieuw proberen
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}`);
}
});
Implementeer voor 429 (HTTP)-, 409 (HTTP)- en 4290 (WSS)-fouten exponentiële backoff: wacht 1 sec, dan 2 sec, dan 4 sec, enz. Dit voorkomt overbelasting van de API en garandeert dat je verzoek slaagt zodra de vergrendeling is opgeheven.
Voor vragen of problemen met betrekking tot de API kun je contact met ons opnemen via api@moknah.io.