Error Handling - Modellix

Error Response Format

All error responses follow a unified JSON format:

{
  "code": 400,
  "message": "Invalid parameters: parameter 'prompt' is required"
}

Field Descriptions

Field	Type	Required	Description
code	integer	✅	Error code (equals HTTP status code)
message	string	✅	Error message in format `"<Category>: <detail>"`

Note:

❌ data.error nested field is no longer used
✅ message contains both category and detailed information

Error Codes Reference

Response Code Rules

Success: code = 0, HTTP status code 200
Error: code = HTTP status code (e.g., 400, 401, 404, 429, 500, 503)

HTTP Status Codes

HTTP Status	code	Description	Common Scenarios
200	0	Success	Request processed successfully
400	400	Bad Request	Missing required parameters, invalid format, invalid values
401	401	Unauthorized	Invalid API key, missing API key, expired API key
404	404	Not Found	Task ID not found, model not found, provider not found
429	429	Too Many Requests	Rate limit exceeded, quota exceeded
500	500	Internal Server Error	Internal processing error, unexpected error
503	503	Service Unavailable	Service temporarily unavailable, circuit breaker open

400 - Bad Request

Error Categories

Category	Use Case
`Invalid parameters`	Parameter validation failed (general)
`Missing required parameter`	Required parameter missing
`Invalid format`	Parameter format error
`Value out of range`	Parameter value out of range

Examples

Missing required parameter:

{
  "code": 400,
  "message": "Invalid parameters: parameter 'prompt' is required"
}

Invalid format:

{
  "code": 400,
  "message": "Invalid format: parameter 'size' must be in format 'width*height', got '1024'"
}

Value out of range:

{
  "code": 400,
  "message": "Value out of range: parameter 'steps' must be between 10 and 50, got 100"
}

Invalid JSON format:

{
  "code": 400,
  "message": "Invalid format: invalid JSON format"
}

401 - Unauthorized

Error Categories

Category	Use Case
`Authentication failed`	Authentication failure

Examples

Missing API key:

{
  "code": 401,
  "message": "Authentication failed: missing Authorization header"
}

Invalid API key:

{
  "code": 401,
  "message": "Authentication failed: invalid API key"
}

Invalid header format:

{
  "code": 401,
  "message": "Authentication failed: invalid header format, expected 'Bearer <token>'"
}

404 - Not Found

Error Categories

Category	Use Case
`Resource not found`	Resource does not exist

Examples

Task not found:

{
  "code": 404,
  "message": "Resource not found: task 'task-abc123' does not exist"
}

Model not found:

{
  "code": 404,
  "message": "Resource not found: model 'qwen-ultra' not found for provider 'alibaba'"
}

429 - Too Many Requests

Error Categories

Category	Use Case
`Rate limit exceeded`	API rate limit
`Concurrent limit exceeded`	Concurrent task limit

Response Headers

When team rate limit is triggered, the response includes these headers:

Header	Type	Description
X-RateLimit-Limit	integer	Maximum requests per minute
X-RateLimit-Remaining	integer	Remaining quota in current window
X-RateLimit-Reset	timestamp	Rate limit reset time (Unix timestamp)

Examples

Team rate limit exceeded:

{
  "code": 429,
  "message": "Rate limit exceeded: 100 requests per minute, retry after 60 seconds"
}

Response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067260

Concurrent limit exceeded:

{
  "code": 429,
  "message": "Concurrent limit exceeded: maximum 3 concurrent tasks allowed"
}

500 - Internal Server Error

Error Categories

Category	Use Case
`Internal server error`	Server internal error

Example

Internal error:

{
  "code": 500,
  "message": "Internal server error"
}

Note: 500 errors do not include technical details to avoid information disclosure.

503 - Service Unavailable

Error Categories

Category	Use Case
`Service unavailable`	Service unavailable

Examples

Service unavailable:

{
  "code": 503,
  "message": "Service unavailable: provider 'alibaba' is temporarily unavailable"
}

Circuit breaker open:

{
  "code": 503,
  "message": "Service unavailable: circuit breaker open, retry later"
}

Best Practices

Retry Strategy

Retryable Error

429 - Too Many Requests:
- Team rate limit: Check X-RateLimit-Reset header, wait until reset time
- Concurrent limit: Wait for running tasks to complete
- Use exponential backoff
500 - Server Error: Retry after short wait (max 3 retries)
503 - Service Unavailable: Retry after longer wait (use exponential backoff)

Non-Retryable Errors

400 - Bad Request: Fix parameters and retry
401 - Unauthorized: Provide valid API key
404 - Not Found: Check resource ID

Exponential Backoff

Retry interval calculation:

1st retry: wait 2^0 = 1 second
2nd retry: wait 2^1 = 2 seconds
3rd retry: wait 2^2 = 4 seconds

Error Logging

Log the following information for debugging:

Request timestamp
Request parameters
Error code
Complete error message (including category and detail)
Request ID (if provided)

User-Friendly Error Messages

Parse error category and provide user-friendly messages:

# Example: Parse error category
response = requests.post(url, headers=headers, json=data)
result = response.json()

if result['code'] != 0:
    message = result['message']
    # Parse category
    if ': ' in message:
        category, detail = message.split(': ', 1)
    else:
        category, detail = message, ''
    
    # Handle by category
    if category == 'Invalid parameters':
        print(f"Invalid input: {detail}")
    elif category == 'Authentication failed':
        print(f"Authentication failed: {detail}")
    elif category == 'Resource not found':
        print(f"Resource not found: {detail}")
    elif category == 'Rate limit exceeded':
        print(f"Too many requests: {detail}")
    else:
        print(f"Error: {message}")

Team-Level Rate Limiting

Monitor Response Headers

# Example: Check rate limit status
curl -i -X POST "https://api.modellix.ai/api/v1/text-to-image/alibaba/qwen-v1/async" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{"prompt": "test"}'

# Response headers:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 95
# X-RateLimit-Reset: 1704067260

Proactive Rate Limiting

Best practices:

Monitor remaining quota: Check X-RateLimit-Remaining regularly
Proactive throttling: Reduce request rate when quota is low
Reserve buffer: Keep 10-20% quota as buffer
Distribute requests: Avoid sending many requests in short time

Example code:

# Check rate limit status
response = requests.post(url, headers=headers, json=data)
remaining = int(response.headers.get('X-RateLimit-Remaining', 100))
limit = int(response.headers.get('X-RateLimit-Limit', 100))

# Proactive throttling when remaining < 20%
if remaining < limit * 0.2:
    time.sleep(1)  # Wait 1 second

Concurrent Task Management

Team concurrent task limit:

All API keys under same team share concurrent task quota
Implement client-side concurrency control to avoid frequent limit triggers
Wait for running tasks to complete when limit is reached

Example:

from threading import Semaphore

max_concurrent = 3  # Match team configuration
semaphore = Semaphore(max_concurrent)

def send_request():
    with semaphore:  # Auto control concurrency
        response = requests.post(url, headers=headers, json=data)
        return response

Timeout Settings

Set appropriate request timeout:

Text-to-image: 30-60 seconds recommended
Text-to-video: 60-120 seconds recommended
Task query: 10-30 seconds recommended

# Example: Set timeout with curl
curl -X POST "https://api.modellix.ai/api/v1/text-to-image/alibaba/qwen-v1/async" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "test"}' \
  --max-time 60  # 60 second timeout

FAQ

Q1: Why do I always get 401 errors? A: Possible reasons:

API key not set or format error (should be Authorization: Bearer YOUR_API_KEY)
API key expired or disabled
API key doesn’t have permission to access this endpoint

Solution: Verify API key is valid and Authorization header format is correct.

Q2: Why do I get 429 errors? A: Rate limiting triggered. Check error message category:

Rate limit exceeded: Team rate limit
- Check X-RateLimit-Reset for reset time
- Reduce request rate
Concurrent limit exceeded: Team concurrent task limit
- Wait for running tasks to complete
- Implement client-side concurrency control

Solution:

Check response headers for remaining quota
Use retry strategy (exponential backoff)
Contact support to upgrade team quota

Q3: Why does task query return 404? A: Possible reasons:

Task ID doesn’t exist or typo
Task expired and cleaned up (results typically retained for 24 hours)
Task belongs to different API key, no access permission

Solution: Check task ID is correct and task hasn’t expired.

Q4: How to distinguish client errors from server errors? A: Based on HTTP status code:

4xx: Client error, need to fix request parameters or authentication
5xx: Server error, can retry or contact support

Getting Started

How to Use

Model API

Common API

​Error Response Format

​Field Descriptions

​Error Codes Reference

​Response Code Rules

​HTTP Status Codes

​400 - Bad Request

​Error Categories

​Examples

​401 - Unauthorized

​Error Categories

​Examples

​404 - Not Found

​Error Categories

​Examples

​429 - Too Many Requests

​Error Categories

​Response Headers

​Examples

​500 - Internal Server Error

​Error Categories

​Example

​503 - Service Unavailable

​Error Categories

​Examples

​Best Practices

​Retry Strategy

​Retryable Error

​Non-Retryable Errors

​Exponential Backoff

​Error Logging

​User-Friendly Error Messages

​Team-Level Rate Limiting

​Monitor Response Headers

​Proactive Rate Limiting

​Concurrent Task Management

​Timeout Settings

​FAQ

Error Response Format

Field Descriptions

Error Codes Reference

Response Code Rules

HTTP Status Codes

400 - Bad Request

Error Categories

Examples

401 - Unauthorized

Error Categories

Examples

404 - Not Found

Error Categories

Examples

429 - Too Many Requests

Error Categories

Response Headers

Examples

500 - Internal Server Error

Error Categories

Example

503 - Service Unavailable

Error Categories

Examples

Best Practices

Retry Strategy

Retryable Error

Non-Retryable Errors

Exponential Backoff

Error Logging

User-Friendly Error Messages

Team-Level Rate Limiting

Monitor Response Headers

Proactive Rate Limiting

Concurrent Task Management

Timeout Settings

FAQ