Skip to main content
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}")