Jump table from symptom → code → what to do . Full field-level contracts stay
in docs/api.md
and docs/troubleshooting.md ;
this page is the cookbook index.
Check Expect Chapter
GET /health200, model is "loading" or a head name01 GET /ready200 before first audio / job04 , 02 version in /healthmatches the binary/image you deployed 06
Gate liveness on /health, readiness on /ready — never on “TCP port is open”.
HTTP Code Typical cause Fix
400 empty_bodyEmpty POST body Send audio bytes 400 invalid_formatBad ?format= Use json / txt / srt / vtt / md — 02 400 unsupported_codecBad ?codec= pcmu / pcma / g722 — 03 400 invalid_sample_rateMissing/out-of-range rate with raw codec Pass sample_rate=8000 or 16000 — 03 400 conflicting_modeschannels=split and diarization=truePick one — 03 403 loopback_onlyNon-loopback POST /v1/admin/reload Call from 127.0.0.1 — 06 404 (no body) / jobs_disabled Jobs API off --enable-jobs — 02 404 job_not_foundUnknown or TTL-evicted job Persist results client-side — 02 409 job_not_finishedResult polled too early Wait for done or poll status 409 job_not_cancellableCancel on terminal job Ignore / treat as done 409 reload_in_progressParallel admin reloads Wait and retry once — 06 409 punctuation_not_availableForced punctuation=true without model Install punct model or use auto — 07 413 payload_too_largeBody > --body-limit-bytes Raise limit or chunk via jobs — 02 , 06 422 invalid_audioCorrupt / unsupported container Check format table — 03 422 transcription_errorDecode ok, inference failed Check logs; try INT8 model present — 07 429 rate_limitedPer-IP bucket empty Wait Retry-After; or raise limits / --trust-proxy — 06 429 queue_fullJobs store full Drain results / raise --jobs-max — 02 503 timeoutPool saturated Back off Retry-After; raise --pool-size — 07 503 pool_closedShutdown in progress Reconnect after deploy — 06 503 initializingModel still loading (WS upgrade or ready) Poll /ready — 01 503 reload_failed / reload_unsupportedHot-reload build failed / no builder Fix model files; keep old engine — 06 504 inference_timeoutOne run > --inference-timeout-secs Raise timeout for long files — 02
Code Session Meaning Fix
timeoutnever opened Pool checkout timed out Wait retry_after_ms, reconnect — 04 pool_closedends Server draining Reconnect after upgrade — 06 idle_timeoutends (1001) No frames for --idle-timeout-secs Keep streaming PCM (silence is fine) — 04 max_session_duration_exceededends (1008) Hit --max-session-secs Reconnect; final was flushed — 04 policy_violationends (1008) Empty-frame spam Stop sending empty binaries inference_timeoutends Chunk inference too long Shorter audio / raise timeout inference_errorcontinues Bad chunk Fix client audio; session kept inference_paniccontinues, state reset Panic isolated Treat as new utterance; keep prior finals configure_too_latecontinues configure after first audioSend configure first — 04 invalid_sample_ratecontinues Rate not in supported_rates Use a rate from ready unsupported_protocol_versionends Client protocol mismatch Speak 1.0 — 04
Code When Client action
1001 Going Away SIGTERM drain, idle, ping timeout Reconnect; expect a flushed final on shutdown 1008 Policy Violation max session / empty spam Adjust caps or client behaviour 1009 Message Too Big Frame > --ws-frame-max-bytes Smaller PCM frames 1006 Abnormal Closure No close frame (kill, crash, middlebox) Check process health; not a protocol code the server sends