Getting Started

Getting Started

API

MCP Server

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_url and image_urls provided
  • Invalid URL format

401 — Authentication Error

{
  "error": {
    "message": "Invalid or missing API key",
    "type": "authentication_error"
  }
}

Common causes:

  • Missing Authorization header
  • 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")

Table of Contents

Error Handling
Error Types
400 — Invalid Request
401 — Authentication Error
402 — Insufficient Credits
429 — Rate Limit Exceeded
500 — Internal Server Error
Task Failure Handling
Retry Strategy