Error Handling
How to handle API errors and edge cases
Error Handling
All errors follow a consistent format:
{
"error": {
"message": "Human-readable error message",
"type": "error_type",
"code": "specific_code",
"param": null
}
}Error Types
400 — Invalid Request
{
"error": {
"message": "Provide either image_url or image_urls, not both",
"type": "invalid_request_error"
}
}Common causes:
- Missing required parameters
- Invalid model name
- Both
image_urlandimage_urlsprovided - Invalid URL format
401 — Authentication Error
{
"error": {
"message": "Invalid or missing API key",
"type": "authentication_error"
}
}Common causes:
- Missing
Authorizationheader - Key has been deleted
- Key is malformed
402 — Insufficient Credits
{
"error": {
"message": "Insufficient credits. Required: 10, available: 5",
"type": "credits_error",
"code": "insufficient_credits"
}
}Purchase more credits at Settings → Credits.
429 — Rate Limit Exceeded
{
"error": {
"message": "Rate limit exceeded",
"type": "rate_limit_error"
}
}Wait and retry. See Authentication for rate limits by tier.
500 — Internal Server Error
{
"error": {
"message": "Internal server error",
"type": "api_error"
}
}Retry with exponential backoff. If persistent, contact support.
Task Failure Handling
Task failures (as opposed to HTTP errors) are returned in the task object:
{
"status": "failed",
"error": {
"message": "3D generation failed: invalid input image",
"type": "generation_error"
},
"usage": {
"credits_refunded": 10,
"credits_remaining": 1000
}
}Credits are automatically refunded when a task fails. No action needed.
Retry Strategy
import time
def create_generation_with_retry(image_url, model, max_retries=3):
for attempt in range(max_retries):
resp = requests.post(
"https://trellis2.app/api/v1/3d/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"image_url": image_url, "model": model, "mode": "async"}
)
if resp.status_code == 429:
wait = 2 ** attempt
time.sleep(wait)
continue
return resp.json()
raise Exception("Max retries exceeded")