Error Codes

The Audixa API uses HTTP status codes to indicate the success or failure of requests. Endpoint-specific details can add context to the common responses below.

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, including an accepted `POST /tts` job

Client Error Codes

Code	Status	Description
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Missing or invalid API key
`402`	Payment Required	Insufficient balance
`403`	Forbidden	The active plan cannot access the requested model or voice
`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)
Invalid model value (must be base or advanced)
Empty text or text longer than the active plan limit
Voice and model are incompatible

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 at least $10 or start a subscription in 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
The generation belongs to another account

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

Handle transport errors directly, then handle the asynchronous FAILED status while polling:

response = requests.post(API_URL, headers=headers, json=payload, timeout=30)

if response.status_code == 429:
    retry_after = response.headers.get("Retry-After")
    raise RuntimeError(f"Rate limited; Retry-After={retry_after}")
if response.status_code == 402:
    raise RuntimeError("Insufficient balance")

response.raise_for_status()
generation = response.json()

const response = await fetch(API_URL, options);
if (response.status === 429) {
  throw new Error(`Rate limited; Retry-After=${response.headers.get('Retry-After')}`);
}
if (response.status === 402) throw new Error('Insufficient balance');
if (!response.ok) throw new Error(await response.text());

const generation = await response.json();

Getting Started

API Guides

Language Examples

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