Error Codes & Troubleshooting - SLNG Documentation

Authentication errors

Error	Cause	Fix
HTTP 401	Missing or invalid SLNG key	Check the `Authorization: Bearer SLNG_API_KEY` header. Verify the key is active in the Dashboard.
WebSocket rejected with 401	SLNG key not passed in the handshake	Pass the key as a header (`Authorization: Bearer SLNG_API_KEY`) or query parameter (`?token=SLNG_API_KEY`).
`X-Slng-Auth-Source: client_key`	BYOK provider key rejected upstream	Your provider key was rejected, not the SLNG key. Check the key with the provider directly.

Error code	Meaning	What to do
`auth_error`	Invalid or missing SLNG key	Check your Authorization header.
`config_error`	Invalid session configuration	Verify your `init` message parameters.
`rate_limit`	Too many concurrent connections	Back off and retry with exponential delay.
`provider_error`	Upstream model returned an error	Check model availability; consider configuring failover models.
`backend_connection_failed`	Could not connect to upstream model	The model may be temporarily unavailable; retry or use a fallback.

Status	Code	Meaning
400	`invalid_pronunciation`	Malformed object, invalid name, unsupported mode, or dictionary not found
401	`pronunciation_unauthenticated`	Missing or unresolved organization context
409	`pronunciation_conflict`	Dictionary name already exists in your organization
503	`pronunciation_unavailable`	Platform dependency failure during dictionary resolution

WebSocket pronunciation errors return an error frame:

{
  "type": "error",
  "code": "pronunciation_not_found",
  "message": "Pronunciation dictionary not found: support-pronunciations"
}

WebSocket disconnects unexpectedly.

Implement reconnection with exponential backoff (1s, 2s, 4s, up to 30s).
Send periodic keep-alive messages ({"type": "keepalive"} for STT) to prevent idle timeouts.
If behind a corporate proxy, confirm it supports WebSocket upgrades (the Connection: Upgrade header).

Buffer at least 200ms of audio before starting playback.
Use the WebAudio API (AudioContext) instead of <audio> elements for gapless chunk playback.
Confirm your player’s sample rate matches the sample_rate from your init config.
24kHz linear16 audio requires roughly 384 kbps. Verify your connection can sustain it.

Send audio in 20-100ms chunks (320-1600 bytes at 16kHz linear16).
Confirm encoding and sample_rate in your init config match your actual audio format.
For real-time use, prefer Deepgram Nova, which is optimized for streaming latency.

Keep your audio configuration consistent across the pipeline:

{
  "encoding": "linear16",
  "sample_rate": 16000
}

Your audio capture must match: 16-bit samples, 16000 Hz, single channel (mono).