API
错误处理
如何处理 API 错误和边界情况
错误处理
所有错误遵循统一的格式：
{
"error": {
"message": "人类可读的错误信息",
"type": "error_type",
"code": "specific_code",
"param": null
}
}错误类型
400 — 无效请求
{
"error": {
"message": "Provide either image_url or image_urls, not both",
"type": "invalid_request_error"
}
}常见原因：
- 缺少必填参数
- 无效的模型名称
- 同时提供了
image_url和image_urls - URL 格式无效
401 — 认证错误
{
"error": {
"message": "Invalid or missing API key",
"type": "authentication_error"
}
}常见原因：
- 缺少
Authorization请求头 - 密钥已被删除
- 密钥格式错误
402 — 积分不足
{
"error": {
"message": "Insufficient credits. Required: 10, available: 5",
"type": "credits_error",
"code": "insufficient_credits"
}
}请在 设置 → 积分 购买更多积分。
429 — 速率限制
{
"error": {
"message": "Rate limit exceeded",
"type": "rate_limit_error"
}
}请等待后重试。各等级的速率限制请参见 认证。
500 — 内部服务器错误
{
"error": {
"message": "Internal server error",
"type": "api_error"
}
}请使用指数退避策略重试。如果持续出现，请联系支持。
任务失败处理
任务失败（与 HTTP 错误不同）在任务对象中返回：
{
"status": "failed",
"error": {
"message": "3D generation failed: invalid input image",
"type": "generation_error"
},
"usage": {
"credits_refunded": 10,
"credits_remaining": 1000
}
}任务失败时积分会 自动退还。无需任何操作。
重试策略
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("已超过最大重试次数")