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", "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 credits
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

​
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 'advance'"}
  ]
}
Common causes:
  • Missing required fields (text, voice, model)
  • Invalid model value (must be base or advance)
  • 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 credits. 
{
  "detail": "Insufficient Balance"
}
Solution: Add credits 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

import requests

response = requests.post(
    "https://api.audixa.ai/v2/tts",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"text": "Hello", "voice": "aura-asteria-en", "model": "base"}
)

if response.status_code == 201:
    print("Success:", response.json())
elif response.status_code == 401:
    print("Authentication failed. Check your API key.")
elif response.status_code == 402:
    print("Insufficient credits. Please add funds.")
elif response.status_code == 429:
    print("Rate limited. Retry later.")
else:
    print(f"Error {response.status_code}:", response.json().get("detail"))