Unprocessable Entity

What this error means

Root causes

How to fix it

1. 1

   Validate request body JSON syntax

   Use a JSON validator tool or parse your request body through a JSON linter. Common issues include missing commas, trailing commas, unescaped quotes, or missing curly braces. Ensure your entire payload is valid JSON before sending.

2. 2

   Verify the 'text' parameter exists and is not empty

   Ensure you're including a 'text' field in your request body and that it contains actual content. Check for null values, undefined, or whitespace-only strings. The text parameter must be a non-empty string.

3. 3

   Confirm 'voice_id' is valid and accessible

   Call the ElevenLabs voices endpoint (GET /v1/voices) to retrieve a list of available voice IDs, then verify you're using an ID from that list. Common mistakes include typos, using voice names instead of IDs, or referencing voices you don't have access to.

   curl -H 'xi-api-key: YOUR_API_KEY' https://api.elevenlabs.io/v1/voices

4. 4

   Check that 'model_id' is supported and specified

   Ensure you're using a valid model_id such as 'eleven_monolingual_v1', 'eleven_multilingual_v2', or the latest available model. List available models via the API or check ElevenLabs documentation for current model names. If model_id is omitted, ElevenLabs may use a default, but explicitly setting it prevents ambiguity.

   {
     "text": "Hello world",
     "voice_id": "21m00Tcm4TlvDq8ikWAM",
     "model_id": "eleven_monolingual_v1"
   }

5. 5

   Verify request headers are correct

   Set the Content-Type header to 'application/json' and ensure your xi-api-key header contains a valid API key. Missing or incorrect headers can cause the request to be misinterpreted.

6. 6

   Check text length constraints

   If your text parameter is very long, split it into smaller chunks. ElevenLabs typically has a character limit per request (around 5000 characters depending on the model). If you exceed this, break your text into multiple requests.

   const maxLength = 5000;
   const textChunks = text.match(new RegExp(`.{1,${maxLength}}`, 'g'));
   for (const chunk of textChunks) {
     // Send each chunk separately
   }

7. 7

   Log and inspect the actual request before sending

   Print out the exact JSON payload and headers being sent to ElevenLabs. This often reveals hidden issues like encoding problems, unexpected null values, or parameter mismatches that aren't obvious in code review.

   console.log(JSON.stringify(requestBody, null, 2));
   console.log('Headers:', headers);

Prevention

Implement strict input validation on the client side before sending requests to ElevenLabs. Create a request schema validator that checks for the presence of required fields (text, voice_id, model_id), validates their data types, and verifies text length before transmission. Cache valid voice_id and model_id values from the ElevenLabs API on application startup, and use them as an allowlist to prevent invalid IDs from being submitted. Additionally, add comprehensive logging and error handling to capture the exact request payload whenever a 422 error occurs, enabling faster debugging in production. Test your integration with ElevenLabs' sandbox or test endpoints before deploying to production.