Troubleshooting
Real-time translation
GET /v1/session returns 401 or 403
401— missing or invalid API key. Check theAuthorization: Bearer …header and confirm the key in the Developer Portal.403— the key is valid but isn’t entitled to real-time translation. Reach out to support@startpinch.com.
GET /v1/session returns 503
Capacity is temporarily exhausted. Retry with a short backoff (e.g. 1 s, then 2 s). If you see this persistently, let us know at support@startpinch.com so we can provision more capacity.
WebSocket handshake fails with 401
The pre-signed ws_url token has expired or is malformed. Tokens are valid
for 60 seconds after GET /v1/session; open the socket promptly. Create a
new session.
WebSocket closes with code 4503 or 1001
The server that accepted the socket had no capacity (4503) or is shutting
down (1001). Create a new session via GET /v1/session.
error frame right after ready, then the socket closes
The session parameters were rejected. The error text names the parameter:
an unknown modelName, a voiceId that isn’t in GET /v1/voices,
voiceId=auto or sourceLanguage=auto on relay-1, sourceLanguage=auto
together with twoWay=true, a malformed languageHints, or a
targetLanguage without voice output while audioOutputEnabled=true.
I sent audio but never got ready
ready is the first frame from the server. Don’t send audio before it
arrives. If ready never arrives, the ws_url may have expired —
reallocate.
No transcripts coming back
- Check you’re sending PCM16 little-endian, mono, 16 kHz on the binary channel.
- Check frames aren’t empty or silence-only — some voiced audio is required before recognition kicks in.
- Check the
sourceLanguageis actually the language being spoken, or usesourceLanguage=autoonrelay-2.
Last sentence doesn’t finalise (push-to-talk)
If you stop sending audio the instant the user releases a key, the
server never sees enough trailing silence to finalise the segment. Send
{"type":"finalize"} when the key is released — see
finalize. Sending ~300 ms of silence
(PCM16 zeros) also works, with more tail latency.
Translated audio sounds garbled or slowed
Usually the same root cause as “last sentence doesn’t finalise” —
segments stuck in a continuation state get rendered at a slower rate.
Send finalize as described above.
Every speaker sounds the same
voiceId=auto needs modelName=relay-2; relay-1 does not separate
speakers. A speaker’s first line may use the default voice until
the match lands. If two people share a voice for the whole session, the
library had no closer match for one of them — pin a voiceId explicitly.
Translation is in the wrong language with sourceLanguage=auto
Detection is decided from the first words of each utterance. Pass
languageHints with the languages you expect so a short or accented
opening isn’t matched to a language that won’t occur. If the set of
languages is known and fixed, pin sourceLanguage instead.
error frame — targetLanguage='xx' is not supported
The target language you requested isn’t in the speech output set. Either
pick a supported output language (see
Supported languages) or pass
audioOutputEnabled=false to get transcripts only.
error frame — voiceType='clone' is not available yet
Voice cloning is not available on the real-time API. Pick a voice from
GET /v1/voices and pass it as voiceId, or use voiceType male /
female.
error frame — voiceId is not a valid Pinch voice
The ID is not in GET /v1/voices. Voice IDs are numeric; names are not
accepted.
Dubbing
Job stuck in processing
Dubbing jobs scale with audio duration. A 1-hour file typically finishes
in under 15 minutes; longer waits usually mean the upstream media
couldn’t be fetched. Check the job’s error field and confirm the
source_url is publicly reachable.
400 from POST /api/dubbing/jobs
Most commonly: source_url can’t be fetched, unsupported media
container, or the source language isn’t supported. The response body
names the specific field.
Still stuck?
Email support@startpinch.com with your
session_id (for real-time) or job ID (for dubbing) and a short
description of what you’re seeing.