---
title: "Troubleshooting"
section: "Resources"
order: 0
---

## Real-time translation

### `GET /v1/session` returns `401` or `403`

- `401` — missing or invalid API key. Check the `Authorization: Bearer …`
  header and confirm the key in the
  [Developer Portal](https://portal.startpinch.com/dashboard/developers).
- `403` — the key is valid but isn't entitled to real-time translation.
  Reach out to [support@startpinch.com](mailto: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](mailto: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 `sourceLanguage` is actually the language being spoken, or
  use `sourceLanguage=auto` on `relay-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](/docs/api-reference#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](/docs/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](mailto:support@startpinch.com) with your
`session_id` (for real-time) or job ID (for dubbing) and a short
description of what you're seeing.