Moknah Docs
Gratis starten
API-referentie

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

HTTP: 401 WSS: 4001 / 4002

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

HTTP: 402 WSS: JSON tijdens stream

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

HTTP: 409 / 429 WSS: 4290

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

HTTP: 400 WSS: JSON tijdens stream

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}`);
    }
});
Best practice: exponentiële backoff

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.

API-ondersteuning

Voor vragen of problemen met betrekking tot de API kun je contact met ons opnemen via api@moknah.io.