Error Codes

The Audixa API uses standard HTTP status codes to indicate the success or failure of requests. This guide documents all possible error responses.

Error Response Format

All error responses follow a consistent JSON format:

{
  "detail": "Human-readable error message"
}

Some errors may include additional context:

{
  "detail": "Validation error",
  "errors": [
    {"field": "text", "message": "Text is required"},
    {"field": "voice_id", "message": "Invalid voice ID"}
  ]
}

HTTP Status Codes

Success Codes

Code	Status	Description
`200`	OK	Request succeeded (GET requests)
`201`	Created	Resource created successfully (POST /tts)

Client Error Codes

Code	Status	Description
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Missing or invalid API key
`402`	Payment Required	Insufficient balance
`404`	Not Found	Resource not found (e.g., invalid generation_id)
`422`	Unprocessable Entity	Validation error
`429`	Too Many Requests	Rate limit exceeded

Server Error Codes

Code	Status	Description
`500`	Internal Server Error	Unexpected server error
`503`	Service Unavailable	Service temporarily unavailable

WebSocket Close Codes

Code	Description
`1003`	Invalid Payload: The server received data it cannot accept (e.g., malformed JSON).
`1008`	Policy Violation: Authentication failed (e.g., invalid API key).
`1011`	Internal Error: Unexpected server condition (e.g., Redis failure).

Common Errors

400 Bad Request

Returned when request parameters are missing or invalid.

{
  "detail": "Validation error",
  "errors": [
    {"field": "text", "message": "Text is required"},
    {"field": "model", "message": "Model must be 'base' or 'advanced'"}
  ]
}

Common causes:

Missing required fields (text, voice_id, model)
Invalid model value (must be base or advanced)
Text exceeds maximum length

401 Unauthorized

Returned when authentication fails.

{
  "detail": "Invalid or missing API key"
}

Common causes:

Missing x-api-key header
Invalid or revoked API key

402 Payment Required

Returned when your account has insufficient balance.

{
  "detail": "Insufficient Balance"
}

Solution: Add funds via the Billing Dashboard.

404 Not Found

Returned when a requested resource doesn’t exist.

{
  "detail": "Generation not found"
}

Common causes:

Invalid generation_id when checking status
Generation expired (older than 24 hours)

429 Too Many Requests

Returned when you exceed the rate limit.

{
  "detail": "Rate limit exceeded. Please retry after 30 seconds."
}

Solution: Implement exponential backoff retry logic. See Rate Limits.

500 Internal Server Error

Returned when an unexpected server error occurs.

{
  "detail": "An unexpected error occurred. Please try again."
}

Solution: Retry the request. If the error persists, contact support@audixa.ai.

Error Handling Example

Both SDKs provide typed error classes for robust error handling:

import audixa
from audixa.exceptions import (
    AudixaError,
    AuthenticationError,
    RateLimitError,
    InsufficientBalanceError,
)

audixa.set_api_key("YOUR_API_KEY")

try:
    audio_url = audixa.tts_and_wait(
        "Hello from Audixa!",
        voice_id="am_ethan",
        model="base",
    )
    print("Success:", audio_url)
except AuthenticationError:
    print("Authentication failed. Check your API key.")
except InsufficientBalanceError:
    print("Insufficient balance. Please add funds.")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds.")
except AudixaError as e:
    print(f"API Error ({e.status_code}): {e.message}")

import Audixa, { AudixaError } from 'audixa';

const audixa = new Audixa('YOUR_API_KEY');

try {
  const audioUrl = await audixa.generateTTS({
    text: 'Hello from Audixa!',
    voice_id: 'am_ethan',
    model: 'base'
  });
  console.log('Success:', audioUrl);
} catch (error) {
  if (error instanceof AudixaError) {
    switch (error.code) {
      case 'AUTHENTICATION_ERROR':
        console.log('Authentication failed. Check your API key.');
        break;
      case 'INSUFFICIENT_BALANCE':
        console.log('Insufficient balance. Please add funds.');
        break;
      case 'RATE_LIMITED':
        console.log('Rate limited. Retry later.');
        break;
      default:
        console.log(`Error (${error.statusCode}): ${error.message}`);
    }
  }
}

import Audixa, { AudixaError } from 'audixa';

const audixa = new Audixa('YOUR_API_KEY');

try {
  const audioUrl = await audixa.generateTTS({
    text: 'Hello from Audixa!',
    voice_id: 'am_ethan',
    model: 'base'
  });
  console.log('Success:', audioUrl);
} catch (error) {
  if (error instanceof AudixaError) {
    switch (error.code) {
      case 'AUTHENTICATION_ERROR':
        console.log('Authentication failed. Check your API key.');
        break;
      case 'INSUFFICIENT_BALANCE':
        console.log('Insufficient balance. Please add funds.');
        break;
      case 'RATE_LIMITED':
        console.log('Rate limited. Retry later.');
        break;
      default:
        console.log(`Error (${error.statusCode}): ${error.message}`);
    }
  }
}

Getting Started

API Guides

SDKs

Dashboard

Error Response Format

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

WebSocket Close Codes

Common Errors

400 Bad Request

401 Unauthorized

402 Payment Required

404 Not Found

429 Too Many Requests

500 Internal Server Error

Error Handling Example

​Error Response Format

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​WebSocket Close Codes

​Common Errors

​400 Bad Request

​401 Unauthorized

​402 Payment Required

​404 Not Found

​429 Too Many Requests

​500 Internal Server Error

​Error Handling Example

Error Response Format

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

WebSocket Close Codes

Common Errors

400 Bad Request

401 Unauthorized

402 Payment Required

404 Not Found

429 Too Many Requests

500 Internal Server Error

Error Handling Example