Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(tts): report a key ElevenLabs rejected as the caller's 401, not a 502

nirholasf55bcd20a0ca
diff --git a/api/_lib/elevenlabs.js b/api/_lib/elevenlabs.js
index e3a38dc5e..9a5a7c0d1 100644
--- a/api/_lib/elevenlabs.js
+++ b/api/_lib/elevenlabs.js
@@ -127,7 +127,12 @@ export async function listVoices({ force = false, apiKey: keyOverride = null } =
}
if (!resp.ok) {
console.error('[elevenlabs] listVoices error', resp.status);
- throw upstreamError(`ElevenLabs returned ${resp.status}`, 502);
+ // `status` stays 502 so existing callers are unchanged; `upstreamStatus`
+ // lets a handler that knows whose key it sent tell "their key is wrong"
+ // (401) apart from "ElevenLabs is broken" and answer accordingly.
+ throw upstreamError(`ElevenLabs returned ${resp.status}`, 502, {
+ upstreamStatus: resp.status,
+ });
}
const data = await resp.json();
diff --git a/api/tts/eleven/library.js b/api/tts/eleven/library.js
index af349de1b..5ec543385 100644
--- a/api/tts/eleven/library.js
+++ b/api/tts/eleven/library.js
@@ -95,6 +95,10 @@ async function handleGet(req, res, apiKey) {
if (!resp.ok) {
const detail = await resp.text().catch(() => '');
console.error('[tts/eleven/library] upstream error', resp.status, detail.slice(0, 300));
+ // Match handlePost: a rejected key is the caller's problem to fix, not a
+ // gateway fault they should retry.
+ if (resp.status === 401)
+ return error(res, 401, 'invalid_key', 'ElevenLabs rejected the key on this request');
return error(res, 502, 'upstream_error', `ElevenLabs returned ${resp.status}`);
}
@@ -153,7 +157,9 @@ async function handlePost(req, res, apiKey, userId) {
} catch {
// Non-JSON body: keep the status-only message.
}
- return error(res, resp.status === 401 ? 401 : 422, 'upstream_error', message);
+ return resp.status === 401
+ ? error(res, 401, 'invalid_key', 'ElevenLabs rejected the key on this request')
+ : error(res, 422, 'upstream_error', message);
}
const data = await resp.json().catch(() => ({}));
diff --git a/api/tts/eleven/voices.js b/api/tts/eleven/voices.js
index 54f2dcb82..843587ad3 100644
--- a/api/tts/eleven/voices.js
+++ b/api/tts/eleven/voices.js
@@ -44,6 +44,20 @@ export default wrap(async (req, res) => {
result = await listVoices(source === 'platform' ? {} : { apiKey });
} catch (e) {
console.error('[tts/eleven/voices] listVoices failed', e);
+ // ElevenLabs rejecting the key is not a gateway fault. When the key came
+ // from the caller (an x-eleven-key header or one they saved), say so at
+ // 401 so the client can prompt for a new key instead of retrying a 502
+ // that will never clear.
+ if (e.upstreamStatus === 401) {
+ return error(
+ res,
+ source === 'platform' ? 503 : 401,
+ source === 'platform' ? 'not_configured' : 'invalid_key',
+ source === 'platform'
+ ? 'ElevenLabs rejected this server key'
+ : 'ElevenLabs rejected your key. Check it at /dashboard/account.',
+ );
+ }
return error(
res,
e.status || 502,
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 321ed28b4..e2816311d 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -874,7 +874,9 @@ Search the public catalog ElevenLabs users share (`q`, `gender`, `accent`,
`POST { publicUserId, voiceId, name }` to copy one into the account behind the
request (yours with `x-eleven-key`, the platform's otherwise). The POST returns
a normal `voice_id` usable with `/api/tts/synthesize`. Both require auth and an
-ElevenLabs key.
+ElevenLabs key. A key ElevenLabs rejects returns `401 invalid_key` (here and on
+`/api/tts/eleven/voices`), so a client knows to ask for a new key rather than
+retry a `502` that will never clear.
### Text-to-speech (ElevenLabs, streaming)
diff --git a/docs/voice-lab.md b/docs/voice-lab.md
index a22b3aa61..b50bec1bd 100644
--- a/docs/voice-lab.md
+++ b/docs/voice-lab.md
@@ -143,6 +143,7 @@ The agent-voice handler ([`api/agents/_id/voice.js`](../api/agents/_id/voice.js)
- **Recorder states.** `idle` -> `recording` (live waveform, timer, level meter) -> `review` (playback, name, Clone / Re-record) -> `cloning` (spinner) -> `done` (green check, `voice_id` shown, actions: Try in playground / Add to an agent / Record another).
- **Auth.** The free lanes (Edge, Gemini, NVIDIA) serve anonymous callers on `/api/tts/synthesize` and `/api/tts/catalog`, rate-limited per IP. The metered lanes (OpenAI, ElevenLabs), cloning, and the Voice Library return `401 unauthorized` without a session or bearer token.
- **Server config.** ElevenLabs must be configured (`ELEVENLABS_API_KEY`) or the endpoints return `503 not_configured`; a request carrying its own `x-eleven-key` header still works (see the billing section above). `/api/tts/eleven-clone` checks who is asking first, so a signed-out caller gets `401` and never a reading of what this deployment has configured.
+- **A rejected key reads as a key problem.** When ElevenLabs turns down the key on a request, `/api/tts/eleven/voices` and both `/api/tts/eleven/library` methods answer `401 invalid_key` rather than `502`, so the UI can prompt for a new key instead of retrying. A rejected *platform* key still reads as `503 not_configured`, because that one is ours to fix.
- **Voice ids are checked against the lane.** `POST /api/tts/synthesize` rejects a `voiceId` the chosen lane does not publish with `400 validation_error`, naming the id and the catalog URL to pick from, before anything is metered. It is never quietly swapped for the lane default (omit `voiceId` if that is what you want). ElevenLabs, whose catalog grows at runtime, reports an unknown id as a `400` from upstream instead.
- **Paid cloning tier.** Instant Voice Cloning is an ElevenLabs paid-tier (Starter and up) feature. On a free upstream tier the API surfaces the upstream `can_not_use_instant_voice_cloning` body verbatim as a `502`.
- **Length rules.** Voice Lab recommends 20 to 30 seconds, auto-stops at 60, and rejects under 3. The separate agent-clone endpoint (`POST /api/agents/:id/voice/clone`) enforces a 30-second floor. Platform-key clones on both endpoints are capped at 3 per user per day (an abuse guard on the shared account's limited clone slots) and each is charged per the billing section; BYOK clones on `/api/tts/eleven-clone` skip the cap.
diff --git a/prompts/swarm-100/api-tts-01.md b/prompts/swarm-100/api-tts-01.md
deleted file mode 100644
index 061148e65..000000000
--- a/prompts/swarm-100/api-tts-01.md
+++ /dev/null
@@ -1,109 +0,0 @@
-# API audit: api/tts batch 01 (9 files)
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option
- list, or an unexecuted plan. A judgment call goes in one line of the final
- report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-1. Confirm each file below still exists; deleted ones are done, skip them.
-2. For each, decide routability: grep its path in vercel.json and read how
- server/index.mjs maps filesystem handlers. Routed files get an endpoint
- audit; internal modules get a code and test audit.
-3. Start a local server for endpoint checks: node server/index.mjs with .env
- loaded, on a free PORT if 3000 is busy.
-
-## Task: audit these api files, then fix everything found
-
-Files in this batch:
-
-- api/tts/catalog.js
-- api/tts/edge.js
-- api/tts/eleven-clone.js
-- api/tts/eleven.js
-- api/tts/eleven/library.js
-- api/tts/eleven/voices.js
-- api/tts/speak.js
-- api/tts/synthesize.js
-- api/tts/voices.js
-
-For every routed handler:
-
-1. Exercise it with curl against the local server: the success path returns
- real data with the correct status; malformed input returns a 4xx JSON
- error, never a stack trace or an HTML error page; auth is enforced where
- the code intends it; CORS matches neighboring handlers.
-2. Hard-rule scan: no mock fallbacks, no fake-data arrays, no stubbed
- responses, no unfinished markers. Errors are handled at the boundary and
- internal code trusts itself.
-3. Do not spend funds or sign anything on-chain while probing. Payment and
- trading handlers get their validation and error paths exercised, never a
- live settlement.
-
-For every internal (non-routed) module:
-
-4. Something must import it; if nothing does, delete it as dead code (verify
- with a repo-wide grep first).
-5. Its main path and one failure path must be covered in tests/; add the
- missing test if not.
-
-## Definition of done
-
-- [ ] Every listed file has recorded evidence: a curl transcript for routed
- handlers, a passing test or a deletion for internal modules.
-- [ ] Zero hard-rule violations remain in these files.
-- [ ] vitest run passes; npm run check:rules -- --paths <touched files>
- exits 0.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in
- front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/api-tts-01.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.
diff --git a/tests/api/tts-input-guards.test.js b/tests/api/tts-input-guards.test.js
index 15e0ac47d..34221c911 100644
--- a/tests/api/tts-input-guards.test.js
+++ b/tests/api/tts-input-guards.test.js
@@ -390,6 +390,47 @@ describe('an unknown ElevenLabs voice is the caller\'s error, not the platform\'
});
});
+describe('a key ElevenLabs rejects is reported as a key problem, not a gateway fault', () => {
+ it('GET /api/tts/eleven/voices answers 401 invalid_key for a caller-supplied key', async () => {
+ vi.resetModules();
+ stubFetch({ elevenStatus: 401 });
+ signIn();
+ const res = await call('../../api/tts/eleven/voices.js', {
+ method: 'GET',
+ url: '/api/tts/eleven/voices',
+ headers: { 'x-eleven-key': 'xi-a-key-this-account-revoked' },
+ });
+ expect(res.statusCode).toBe(401);
+ expect(res.json().error).toBe('invalid_key');
+ });
+
+ it('GET /api/tts/eleven/voices keeps a genuine upstream fault at 502', async () => {
+ vi.resetModules();
+ stubFetch({ elevenStatus: 500 });
+ signIn();
+ const res = await call('../../api/tts/eleven/voices.js', {
+ method: 'GET',
+ url: '/api/tts/eleven/voices',
+ headers: { 'x-eleven-key': 'xi-a-perfectly-good-key' },
+ });
+ expect(res.statusCode).toBe(502);
+ expect(res.json().error).toBe('upstream_error');
+ });
+
+ it('GET /api/tts/eleven/library answers 401, the same way its own POST already did', async () => {
+ vi.resetModules();
+ stubFetch({ elevenStatus: 401 });
+ signIn();
+ const res = await call('../../api/tts/eleven/library.js', {
+ method: 'GET',
+ url: '/api/tts/eleven/library?q=news',
+ headers: { 'x-eleven-key': 'xi-a-key-this-account-revoked' },
+ });
+ expect(res.statusCode).toBe(401);
+ expect(res.json().error).toBe('invalid_key');
+ });
+});
+
describe('POST /api/tts/eleven-clone auth ordering', () => {
it('answers 401 to a signed-out caller rather than reporting the key state', async () => {
process.env.ELEVENLABS_API_KEY = 'xi-platform-key';