Error Handling

The API uses standard HTTP status codes and returns error details in JSON format.

Error Response Format

All error responses follow this structure:

{
  "success": false,
  "statusCode": 400,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits to perform this operation",
    "details": {
      "required": 30,
      "available": 10
    }
  },
  "timestamp": "2024-10-24T10:00:00.000Z",
  "path": "/api/tasks"
}

Response Fields

Field	Type	Description
success	boolean	Always `false` for errors
statusCode	number	HTTP status code
error.code	string	Machine-readable error code
error.message	string	Human-readable error message
error.details	object	Additional error details (optional)
timestamp	string	ISO 8601 timestamp when error occurred
path	string	API endpoint that generated the error

HTTP Status Codes

Code	Description
400	Bad Request - Invalid parameters or insufficient credits
401	Unauthorized - Invalid or missing API key
403	Forbidden - IP not whitelisted or account frozen
404	Not Found - Resource does not exist
409	Conflict - Resource already exists
422	Unprocessable Entity - Validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error occurred

Error Codes

Authentication Errors (1xxx)

INVALID_CREDENTIALS

Status Code: 401

The email or password is incorrect.

{
  "success": false,
  "statusCode": 401,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password"
  }
}

EMAIL_NOT_VERIFIED

Status Code: 403

The email address has not been verified.

{
  "success": false,
  "statusCode": 403,
  "error": {
    "code": "EMAIL_NOT_VERIFIED",
    "message": "Email not verified"
  }
}

ACCOUNT_FROZEN

Status Code: 403

The account has been frozen by an administrator.

{
  "success": false,
  "statusCode": 403,
  "error": {
    "code": "ACCOUNT_FROZEN",
    "message": "Account is frozen"
  }
}

INVALID_TOKEN

Status Code: 401

The authentication token is invalid or expired.

{
  "success": false,
  "statusCode": 401,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Invalid or expired token"
  }
}

EMAIL_ALREADY_EXISTS

Status Code: 409

The email address is already registered.

{
  "success": false,
  "statusCode": 409,
  "error": {
    "code": "EMAIL_ALREADY_EXISTS",
    "message": "Email already exists"
  }
}

Credit Errors (2xxx)

INSUFFICIENT_CREDITS

Status Code: 400

Not enough credits to complete the request.

{
  "success": false,
  "statusCode": 400,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits to perform this operation",
    "details": {
      "required": 30,
      "available": 10
    }
  }
}

Details Fields:

required: Number of credits required for the operation
available: Current credit balance

Task Errors (4xxx)

TASK_NOT_FOUND

Status Code: 404

The requested task does not exist or you don't have access to it.

{
  "success": false,
  "statusCode": 404,
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task not found"
  }
}

TASK_CREATION_FAILED

Status Code: 400

Failed to create the task.

{
  "success": false,
  "statusCode": 400,
  "error": {
    "code": "TASK_CREATION_FAILED",
    "message": "Task creation failed: Invalid prompt"
  }
}

INVALID_PARAMETERS

Status Code: 400

The request parameters are invalid.

{
  "success": false,
  "statusCode": 400,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid parameters: aspectRatio must be 16:9 or 9:16"
  }
}

API Key Errors (5xxx)

INVALID_API_KEY

Status Code: 401

The API key is invalid or expired.

{
  "success": false,
  "statusCode": 401,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key is invalid or expired"
  }
}

Common Causes:

API key was deleted
API key was revoked
Incorrect API key format
Missing Authorization header

IP_NOT_WHITELISTED

Status Code: 403

Your IP address is not in the whitelist.

{
  "success": false,
  "statusCode": 403,
  "error": {
    "code": "IP_NOT_WHITELISTED",
    "message": "IP address 1.2.3.4 is not in the whitelist"
  }
}

Solution: Add your IP address to the API key's whitelist in your dashboard.

Rate Limit Errors (6xxx)

RATE_LIMIT_EXCEEDED

Status Code: 429

Too many requests in a short period.

{
  "success": false,
  "statusCode": 429,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests, please try again in 60 seconds",
    "retryAfter": 60
  }
}

Details Fields:

retryAfter: Number of seconds to wait before retrying

Rate Limits:

All users: 10 requests per second

Error Handling Examples

Python
JavaScript

import requests
from typing import Optional

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://firebirdgen.com'

def create_task_with_error_handling(prompt: str) -> Optional[dict]:
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    data = {
        'requestParams': {
            'projectName': 'sora2',
            'modelName': 'sora2_text_to_video',
            'prompt': prompt,
            'aspectRatio': '9:16',
            'duration': 10
        }
    }
    
    try:
        response = requests.post(
            f'{BASE_URL}/api/tasks',
            json=data,
            headers=headers
        )
        
        # Check if request was successful
        if response.status_code == 200:
            return response.json()['data']
        
        # Handle error response
        error_data = response.json()
        error_code = error_data['error']['code']
        error_message = error_data['error']['message']
        
        if error_code == 'INSUFFICIENT_CREDITS':
            details = error_data['error'].get('details', {})
            required = details.get('required', 0)
            available = details.get('available', 0)
            print(f'Insufficient credits: need {required}, have {available}')
            print('Please purchase more credits')
            
        elif error_code == 'INVALID_API_KEY':
            print('API key is invalid or expired')
            print('Please check your API key in the dashboard')
            
        elif error_code == 'IP_NOT_WHITELISTED':
            print('Your IP is not whitelisted')
            print('Please add your IP to the whitelist')
            
        elif error_code == 'RATE_LIMIT_EXCEEDED':
            retry_after = error_data['error'].get('retryAfter', 60)
            print(f'Rate limit exceeded, retry after {retry_after} seconds')
            
        else:
            print(f'Error: {error_message}')
        
        return None
        
    except requests.exceptions.RequestException as e:
        print(f'Network error: {e}')
        return None

# Usage
result = create_task_with_error_handling('A beautiful sunset')
if result:
    print(f'Task created: {result["taskId"]}')

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://firebirdgen.com';

async function createTaskWithErrorHandling(prompt) {
  try {
    const response = await fetch(`${BASE_URL}/api/tasks`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        requestParams: {
          projectName: 'sora2',
          modelName: 'sora2_text_to_video',
          prompt: prompt,
          aspectRatio: '9:16',
          duration: 10
        }
      })
    });

    const data = await response.json();

    // Check if request was successful
    if (response.ok) {
      return data.data;
    }

    // Handle error response
    const { code, message, details } = data.error;

    switch (code) {
      case 'INSUFFICIENT_CREDITS':
        console.log(`Insufficient credits: need ${details.required}, have ${details.available}`);
        console.log('Please purchase more credits');
        break;

      case 'INVALID_API_KEY':
        console.log('API key is invalid or expired');
        console.log('Please check your API key in the dashboard');
        break;

      case 'IP_NOT_WHITELISTED':
        console.log('Your IP is not whitelisted');
        console.log('Please add your IP to the whitelist');
        break;

      case 'RATE_LIMIT_EXCEEDED':
        const retryAfter = data.error.retryAfter || 60;
        console.log(`Rate limit exceeded, retry after ${retryAfter} seconds`);
        break;

      default:
        console.log(`Error: ${message}`);
    }

    return null;

  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
}

// Usage
createTaskWithErrorHandling('A beautiful sunset').then(result => {
  if (result) {
    console.log('Task created:', result.taskId);
  }
});

Best Practices

Error Handling Best Practices

Always check the response status code before processing the response
Handle specific error codes rather than just checking status codes
Implement retry logic for rate limit errors with exponential backoff
Log errors for debugging and monitoring
Provide user-friendly messages based on error codes
Check credit balance before creating tasks to avoid errors

Retry Logic Example

import time
import requests

def create_task_with_retry(prompt: str, max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            response = requests.post(...)
            
            if response.status_code == 200:
                return response.json()['data']
            
            error_data = response.json()
            error_code = error_data['error']['code']
            
            # Retry on rate limit
            if error_code == 'RATE_LIMIT_EXCEEDED':
                retry_after = error_data['error'].get('retryAfter', 60)
                print(f'Rate limited, waiting {retry_after} seconds...')
                time.sleep(retry_after)
                continue
            
            # Don't retry on other errors
            print(f'Error: {error_data["error"]["message"]}')
            return None
            
        except Exception as e:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                print(f'Attempt {attempt + 1} failed, retrying in {wait_time}s...')
                time.sleep(wait_time)
            else:
                print(f'All retries failed: {e}')
                return None
    
    return None

Troubleshooting

Common Issues

Error	Possible Cause	Solution
INVALID_API_KEY	API key deleted or revoked	Generate a new API key
IP_NOT_WHITELISTED	IP not in whitelist	Add your IP to the whitelist
INSUFFICIENT_CREDITS	Not enough credits	Purchase more credits
RATE_LIMIT_EXCEEDED	Too many requests	Implement rate limiting in your code
TASK_CREATION_FAILED	Invalid parameters	Check parameter values

Getting Help

If you encounter an error that's not documented here:

Check the error message for specific details
Review your request parameters
Check the API status page
Contact support with the error details and timestamp

Next Steps

Create Task - Learn how to create video generation tasks
Query Task - Check task status
Webhook Callbacks - Receive automatic notifications

Error Response Format​

Response Fields​

HTTP Status Codes​

Error Codes​

Authentication Errors (1xxx)​

INVALID_CREDENTIALS​

EMAIL_NOT_VERIFIED​

ACCOUNT_FROZEN​

INVALID_TOKEN​

EMAIL_ALREADY_EXISTS​

Credit Errors (2xxx)​

INSUFFICIENT_CREDITS​

Task Errors (4xxx)​

TASK_NOT_FOUND​

TASK_CREATION_FAILED​

INVALID_PARAMETERS​

API Key Errors (5xxx)​

INVALID_API_KEY​

IP_NOT_WHITELISTED​

Rate Limit Errors (6xxx)​

RATE_LIMIT_EXCEEDED​

Error Handling Examples​

Best Practices​

Retry Logic Example​

Troubleshooting​

Common Issues​

Getting Help​

Next Steps​

Error Response Format

Response Fields

HTTP Status Codes

Error Codes

Authentication Errors (1xxx)

INVALID_CREDENTIALS

EMAIL_NOT_VERIFIED

ACCOUNT_FROZEN

INVALID_TOKEN

EMAIL_ALREADY_EXISTS

Credit Errors (2xxx)

INSUFFICIENT_CREDITS

Task Errors (4xxx)

TASK_NOT_FOUND

TASK_CREATION_FAILED

INVALID_PARAMETERS

API Key Errors (5xxx)

INVALID_API_KEY

IP_NOT_WHITELISTED

Rate Limit Errors (6xxx)

RATE_LIMIT_EXCEEDED

Error Handling Examples

Best Practices

Retry Logic Example

Troubleshooting

Common Issues

Getting Help

Next Steps