LTX-2 API Error Handling

Learn how to handle errors from the LTX-2 API. This guide covers error codes, response formats, and best practices for robust integrations.

Error Response Format

All API errors return a consistent JSON structure containing the error code, message, and additional details.

Error Response Structure

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "field": "Additional context if available",
      "suggestion": "Recommended action to resolve"
    }
  },
  "request_id": "req_abc123xyz"
}

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Task successfully created
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	API key lacks required permissions
404	Not Found	Task or resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error occurred
503	Service Unavailable	Service temporarily unavailable

API Error Codes

These error codes provide specific information about what went wrong with your request.

Authentication Errors

INVALID_API_KEY

The provided API key is invalid or has been revoked.

Solution: Check your API key in the dashboard and ensure it's correctly formatted.

MISSING_API_KEY

No API key was provided in the Authorization header.

Solution: Add "Authorization: Bearer YOUR_API_KEY" to your request headers.

API_KEY_EXPIRED

Your API key has expired.

Solution: Generate a new API key from your dashboard.

Request Validation Errors

INVALID_PROMPT

The prompt is empty, too long, or contains prohibited content.

Solution: Ensure prompt is 1-2000 characters and follows content guidelines.

INVALID_DURATION

Duration must be between 6 and 20 seconds.

Solution: Set duration to a value within the supported range (6-20).

INVALID_RESOLUTION

Resolution must be "1080p", "1440p", or "4K".

Solution: Use one of the supported resolution values.

INVALID_IMAGE_URL

The provided image URL is invalid or inaccessible.

Solution: Ensure the URL is publicly accessible and points to a valid image file.

IMAGE_TOO_LARGE

The input image exceeds the 10MB size limit.

Solution: Compress or resize your image to be under 10MB.

Account & Billing Errors

INSUFFICIENT_CREDITS

Your account doesn't have enough credits for this request.

Solution: Purchase additional credits or upgrade your plan.

RATE_LIMIT_EXCEEDED

You've exceeded the rate limit for your plan.

Solution: Wait before retrying or upgrade to a higher tier for increased limits.

PLAN_LIMIT_REACHED

You've reached the monthly limit for your plan.

Solution: Wait for your billing cycle to reset or upgrade your plan.

Task Processing Errors

TASK_NOT_FOUND

The requested task ID does not exist.

Solution: Verify the task_id and ensure it belongs to your account.

GENERATION_FAILED

The video generation process failed.

Solution: Try again with a different prompt or contact support if the issue persists.

CONTENT_POLICY_VIOLATION

The request violates content policy guidelines.

Solution: Review our content guidelines and modify your prompt.

TIMEOUT

The request timed out during processing.

Solution: Use webhooks for long-running tasks instead of polling.

Error Handling Example

Python Example

import requests

def generate_video(prompt):
    try:
        response = requests.post(
            "https://api.ltx-2api.com/v1/text-to-video",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={"prompt": prompt, "duration": 10}
        )
        response.raise_for_status()
        return response.json()

    except requests.exceptions.HTTPError as e:
        error_data = e.response.json().get("error", {})
        code = error_data.get("code")

        if code == "INSUFFICIENT_CREDITS":
            print("Please add more credits to your account")
        elif code == "RATE_LIMIT_EXCEEDED":
            print("Rate limited. Waiting before retry...")
            time.sleep(60)
            return generate_video(prompt)  # Retry
        elif code == "INVALID_PROMPT":
            print(f"Invalid prompt: {error_data.get('message')}")
        else:
            print(f"Error: {error_data.get('message')}")

        return None

Best Practices

Implement Exponential Backoff

When receiving 429 (rate limit) or 5xx errors, implement exponential backoff with jitter to avoid overwhelming the server.

Log Request IDs

Always log the request_id from error responses. This helps our support team quickly identify and resolve issues.

Use Webhooks for Long Tasks

Instead of polling, configure webhook callbacks to receive notifications when tasks complete or fail.

Validate Before Sending

Validate prompts, durations, and image URLs on your client before sending to avoid unnecessary API calls.