Using the API
Error handling
The error envelope and what each code means.
Every error uses one envelope, so clients handle failures in one place:
503
HTTP/1.1 503 Service Unavailable
{
"error": {
"code": "extraction_unavailable",
"message": "Cannot reach Ollama at http://localhost:11434.",
"details": { "transcription": "بدي ٢ شاورما ووجبة زنجر" }
}
}| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_context | `context` is not valid JSON, or names unknown fields. |
| 400 | unsupported_locale | An override (`locale` / `dialect`) the service does not know. Leave both out for auto. |
| 401 | unauthorized | Missing or wrong API key (when the server requires one). |
| 403 | read_only_schema | Built-in schemas cannot be overwritten or deleted. |
| 404 | unknown_schema / unknown_session | No such schema or version (details list what exists), or the session expired. |
| 409 | version_exists | That schema version is saved with different content. Save a new version. |
| 409 | session_conflict / session_schema_mismatch / session_turn_limit | Two inputs at once, a different schema than the session's, or too many inputs. |
| 413 | audio_too_large / audio_too_long / text_too_long | Over the size or duration limit. |
| 415 | unsupported_media_type | Not an accepted audio type. |
| 422 | invalid_schema | The schema (saved or inline) is not valid. `details.errors` lists each problem with its path. |
| 422 | invalid_audio / no_speech / invalid_request / invalid_review | Unreadable audio, silence, a malformed request, or a review value of the wrong shape. |
| 429 | rate_limited | Too many requests this minute. |
| 503 | extraction_unavailable | The language model is unavailable. `details.transcription` still carries what was heard. |
| 504 | timeout | Processing exceeded the request timeout. |
Limits
| Limit | Default | Setting |
|---|---|---|
| Audio size | 25 MB | MAX_AUDIO_SIZE_MB |
| Audio duration | 120 s | MAX_AUDIO_SECONDS — probed before transcription |
| Text input | 4,000 characters | MAX_TEXT_CHARS |
| Request timeout | 180 s | REQUEST_TIMEOUT_SECONDS |
| Concurrency | 1 job at a time (queued) | MAX_CONCURRENT_JOBS — CPU speech recognition |
| Schema size | 60 fields, 3 levels deep | Checked when a schema is saved or sent inline |
| Sessions | 30 min idle, 20 inputs | SESSION_TTL_MINUTES, MAX_SESSION_TURNS — in memory |
| Rate limit | Off by default | RATE_LIMIT_PER_MINUTE per key or IP |