Exceptions & Error Codes¶

How IndoxHub communicates errors and how to handle them.

Error Response Format¶

All errors return a JSON response with success: false:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "success": false,
  "message": "Human-readable error description",
  "data": ""
}

HTTP Status Codes¶

Code	Name	When
400	Bad Request	Invalid parameters, unsupported model type
401	Unauthorized	Missing or invalid API key
402	Payment Required	Insufficient credits for the request
403	Forbidden	User does not have access to the requested model
404	Not Found	Resource not found (model, job, provider)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error or provider failure
504	Gateway Timeout	Request exceeded timeout (30s default for streams)

Common Error Scenarios¶

Insufficient Credits (402)¶

{
  "success": false,
  "message": "Insufficient credits. Please top up your account."
}

Fix: Add credits via the IndoxHub dashboard or use BYOK.

Model Not Supported (400)¶

{
  "success": false,
  "message": "Model 'invalid/model' is not supported for this endpoint."
}

Fix: Check available models via GET /api/v1/models/.

Model Access Forbidden (403)¶

{
  "success": false,
  "message": "You do not have access to this model."
}

Fix: Contact support or check your account tier.

Provider Error (500)¶

{
  "success": false,
  "message": "Provider error: OpenAI API returned 429 Too Many Requests"
}

Fix: Retry after a delay, or switch to a different provider/model.

Error Handling Best Practice¶

import requests

response = requests.post(
    "https://api.indoxhub.com/api/v1/chat/completions",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "Hi"}]}
)

result = response.json()

if not result.get("success", False):
    error_msg = result.get("message", "Unknown error")
    status = response.status_code

    if status == 402:
        print("Out of credits — top up or use BYOK")
    elif status == 429:
        print("Rate limited — retry after delay")
    elif status >= 500:
        print(f"Server error — try again: {error_msg}")
    else:
        print(f"Error {status}: {error_msg}")
else:
    print(result["data"])