Error Codes

Complete reference of API error codes and their meanings. All errors follow a consistent response shape.

Error Format

Every error response from the API includes an error object with a machine-readable code and a human-readable message. Always branch on code — messages may change between releases.

400Example validation error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'voice_id' is required"
  }
}

Error Code Reference

Code	HTTP	Description
`INVALID_JSON`	400	Request body is not valid JSON
`VALIDATION_ERROR`	400	Input validation failed
`TEXT_TOO_LONG`	400	Text exceeds maximum length for endpoint
`UNAUTHORIZED`	401	Missing or invalid API key
`KEY_EXPIRED`	401	API key has expired
`KEY_REVOKED`	401	API key has been revoked
`INSUFFICIENT_BALANCE`	402	Not enough balance for this request (TTS / music)
`INSUFFICIENT_BALANCE_FOR_IMAGE`	402	Not enough balance for an image generation
`INSUFFICIENT_BALANCE_FOR_VIDEO`	402	Not enough balance for a video generation
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Requested resource not found
`RATE_LIMITED`	429	Rate limit exceeded
`ENGINE_ERROR`	502	TTS engine unavailable or failed
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable

Handling Errors

Use the code field for programmatic branching. Treat 5xx errors as transient and retry with exponential backoff.

async function synthesize(text, voiceId) {
  try {
    const response = await fetch("https://getvrex.com/api/v1/tts", {
      method: "POST",
      headers: {
        "Authorization": "Bearer sk-...",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ text, voice_id: voiceId, format: "mp3" }),
    });

    if (!response.ok) {
      const { error } = await response.json();
      // Use error.code for programmatic handling
      if (error.code === "INSUFFICIENT_BALANCE") {
        throw new Error("Out of balance — please top up your account");
      }
      if (error.code === "RATE_LIMITED") {
        const retryAfter = response.headers.get("Retry-After");
        throw new Error(`Rate limited. Retry in ${retryAfter}s`);
      }
      throw new Error(error.message);
    }

    return response.arrayBuffer();
  } catch (err) {
    console.error("TTS request failed:", err);
    throw err;
  }
}