Error Codes

Understanding API error responses and how to handle them effectively.

All errors include a machine-readable code field for programmatic handling, along with human-readable message and error fields.

HTTP Status Codes

Common HTTP status codes returned by the VideoPilot API:

400

Bad Request

The request was invalid or cannot be served.

Common Causes:

Missing required parameters
Invalid parameter values
Malformed JSON in request body

Example Response:

{
  "error": "Bad Request",
  "message": "Prompt is required",
  "code": "MISSING_REQUIRED_FIELD"
}

401

Unauthorized

Authentication failed or API key is invalid.

Common Causes:

Missing Authorization header
Invalid API key
Expired API key

Example Response:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY"
}

403

Forbidden

The request is valid but you lack permission to access the resource.

Common Causes:

API key lacks required permissions
Account suspended or limited
Resource belongs to another user

Example Response:

{
  "error": "Forbidden",
  "message": "Insufficient permissions",
  "code": "ACCESS_DENIED"
}

404

Not Found

The requested resource was not found.

Common Causes:

Video ID does not exist
Resource deleted or expired
Incorrect endpoint URL

Example Response:

{
  "error": "Not Found",
  "message": "Video not found",
  "code": "VIDEO_NOT_FOUND"
}

422

Unprocessable Entity

The request was well-formed but contains semantic errors.

Common Causes:

Validation errors on input data
Business logic constraints violated
Resource in wrong state for operation

Example Response:

{
  "error": "Unprocessable Entity",
  "message": "Duration must be between 15 and 300 seconds",
  "code": "VALIDATION_ERROR"
}

429

Too Many Requests

Rate limit exceeded. Too many requests in a given time period.

Common Causes:

Exceeded API rate limits
Too many concurrent requests
Burst limit exceeded

Example Response:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60
}

500

Internal Server Error

An unexpected error occurred on the server.

Common Causes:

Server-side processing error
Database connectivity issues
External service failures

Example Response:

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "code": "INTERNAL_ERROR"
}

503

Service Unavailable

The service is temporarily unavailable.

Common Causes:

Server maintenance
High system load
Temporary service outage

Example Response:

{
  "error": "Service Unavailable",
  "message": "Service temporarily unavailable. Please try again later.",
  "code": "SERVICE_UNAVAILABLE"
}

Error Code Reference

Application-specific error codes used in the code field:

Code	HTTP Status	Description
`MISSING_REQUIRED_FIELD`	400	A required parameter was not provided in the request.
`INVALID_API_KEY`	401	The provided API key is invalid or has been revoked.
`VIDEO_NOT_FOUND`	404	The specified video ID does not exist or belongs to another user.
`VIDEO_NOT_READY`	422	The video is not in the correct state for the requested operation.
`RATE_LIMIT_EXCEEDED`	429	Too many requests have been made in the current time window.
`VALIDATION_ERROR`	422	One or more parameters failed validation.
`INSUFFICIENT_CREDITS`	403	Your account does not have enough credits to perform this operation.
`QUOTA_EXCEEDED`	403	Your monthly usage quota has been exceeded.

Error Handling Best Practices

Recommended approaches for handling API errors in your application:

1. Always Check HTTP Status

Check the HTTP status code before processing the response body.

const response = await fetch('https://api.videopilot.app/api/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})

if (!response.ok) {
  const error = await response.json()
  console.error(`API Error: ${error.code} - ${error.message}`)
  // Handle error based on status code
  if (response.status === 401) {
    // Redirect to login
  } else if (response.status === 429) {
    // Implement retry with backoff
  }
}

2. Use Error Codes for Logic

Use the machine-readable code field for conditional logic, not the human-readable message.

try {
  const response = await apiCall()
  return response.data
} catch (error) {
  switch (error.code) {
    case 'VIDEO_NOT_FOUND':
      return null // Handle missing resource
    case 'RATE_LIMIT_EXCEEDED':
      await delay(error.retryAfter * 1000)
      return retry() // Retry after delay
    case 'INSUFFICIENT_CREDITS':
      showUpgradeModal() // Prompt user to upgrade
      break
    default:
      logError(error) // Log unexpected errors
  }
}

3. Implement Retry Logic

Implement exponential backoff for transient errors like rate limits and server errors.

import time
import random

def api_call_with_retry(max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=data)
            
            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:
                # Rate limited - check retry-after header
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue
            elif response.status_code >= 500:
                # Server error - exponential backoff
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
                continue
            else:
                # Client error - don't retry
                response.raise_for_status()
                
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    
    raise Exception("Max retries exceeded")

Rate Limits