Kooma API
Français API keys Sign up

Errors

Kooma uses standard HTTP status codes. Errors return a JSON body with a message readable and a code stable, for programmatic handling.

A 5xx error, or a timeout that keeps happening? First check the service status page, before digging into your code.

StatusCodeCause & fix
400empty_input · empty_text · empty_fileA required field is empty. Check input / text / file.
400unsupported_formatOutput format not supported. Use wav.
401invalid_api_keyMissing or invalid key. Check the header Authorization: Bearer sk-intermo-….
402insufficient_creditsNot enough prepaid credit. Top up your wallet.
403insufficient_scopeThe key lacks the required permission. Add the scope (tts/stt/mt) or create a key inference.
410endpoint_retiredThe service is no longer offered (transcription, subtitling, dubbing). Nothing is billed.
413file_too_largeFile over 80 MB. Compress or split the media.
422aucune_sourceVideo job without a source. Provide file or source_url.
429rate_limitedToo many requests. Wait for the duration given by the header Retry-After.
503tts_unavailable · mt_unavailableHigh demand: retry in 5 minutes (Retry-After header) Retry-After. Not billed.
Shape of an error

The field error.code is stable and safe to test against in your code; error.message may change and is meant for display and logging.

Two error shapes, not one

The endpoints text to speech, translation and voices return the envelope described above. But subtitling et le dubbing return a simpler shape: {"detail": "code_erreur"} — for example job_introuvable, aucune_source, pas_encore_pret.

A robust client therefore reads both: err.error?.code ?? err.detail. We flag it rather than let you discover it in production.

Handling retries well (429 / 503)

Never retry in a tight loop: respect the Retry-After header when present, and add an exponential back-off with jitter for the other cases. One developer who retried 14 times in 25 seconds without respecting this delay took almost an hour to get a first successful response: the base below avoids that.

# Bash / curl — une tentative, lecture de Retry-After en cas de 429/503
resp=$(curl -sS -D headers.txt -o body.json -w '%{http_code}' \
  https://api.kooma.ai/v1/translations \
  -H "Authorization: Bearer $KOOMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"I bɛ tɔgɔ dun ?","source":"bam_Latn","target":"fra_Latn"}')

if [ "$resp" = "429" ] || [ "$resp" = "503" ]; then
  wait=$(grep -i '^retry-after:' headers.txt | tr -dc '0-9')
  sleep "${wait:-5}"
  # ... relance la même requête une fois le délai écoulé
fi
# Python — back-off exponentiel + jitter, 5 tentatives maximum
import random, time, requests

def appeler_avec_retry(url, **kw):
    for tentative in range(5):
        r = requests.post(url, timeout=120, **kw)
        if r.status_code not in (429, 503):
            return r
        attente = float(r.headers.get("Retry-After", 2 ** tentative))
        attente += random.uniform(0, 1)   # jitter : évite que tous les clients ne
                                           # retentent exactement à la même seconde
        time.sleep(attente)
    r.raise_for_status()
    return r

reponse = appeler_avec_retry(
    "https://api.kooma.ai/v1/translations",
    headers={"Authorization": f"Bearer {KOOMA_API_KEY}"},
    json={"text": "I bɛ tɔgɔ dun ?", "source": "bam_Latn", "target": "fra_Latn"},
)
↑↓ navigate↵ openesc close