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.
| Status | Code | Cause & fix |
|---|---|---|
| 400 | empty_input · empty_text · empty_file | A required field is empty. Check input / text / file. |
| 400 | unsupported_format | Output format not supported. Use wav. |
| 401 | invalid_api_key | Missing or invalid key. Check the header Authorization: Bearer sk-intermo-…. |
| 402 | insufficient_credits | Not enough prepaid credit. Top up your wallet. |
| 403 | insufficient_scope | The key lacks the required permission. Add the scope (tts/stt/mt) or create a key inference. |
| 410 | endpoint_retired | The service is no longer offered (transcription, subtitling, dubbing). Nothing is billed. |
| 413 | file_too_large | File over 80 MB. Compress or split the media. |
| 422 | aucune_source | Video job without a source. Provide file or source_url. |
| 429 | rate_limited | Too many requests. Wait for the duration given by the header Retry-After. |
| 503 | tts_unavailable · mt_unavailable | High demand: retry in 5 minutes (Retry-After header) Retry-After. Not billed. |
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.
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"},
)