Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.audixa.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

CodeStatusDescription
200OKRequest succeeded (GET requests)
201CreatedResource created successfully (POST /tts)

​
Client Error Codes

CodeStatusDescription
400Bad RequestInvalid request parameters
401UnauthorizedMissing or invalid API key
402Payment RequiredInsufficient balance
404Not FoundResource not found (e.g., invalid generation_id)
422Unprocessable EntityValidation error
429Too Many RequestsRate limit exceeded

​
Server Error Codes

CodeStatusDescription
500Internal Server ErrorUnexpected server error
503Service UnavailableService temporarily unavailable

​
WebSocket Close Codes

CodeDescription
1003Invalid Payload: The server received data it cannot accept (e.g., malformed JSON).
1008Policy Violation: Authentication failed (e.g., invalid API key).
1011Internal 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}")