Error Codes

Error Response Format

All errors follow a consistent JSON structure:

{
  "error": "Human-readable error message",
  "statusCode": 400,
  "details": {
    // Optional additional context
  }
}

HTTP Status Codes

Imperial uses standard HTTP status codes to indicate success or failure.

Success Codes

Code	Name	Description
200	OK	Request succeeded
201	Created	Resource created successfully (uploads)

Client Error Codes (4xx)

400 Bad Request

The request was malformed or contains invalid parameters.Common Causes:

Missing required fields
Invalid file format
Malformed JSON
Invalid query parameters

Example:

{
  "error": "Validation failed",
  "statusCode": 400,
  "details": {
    "file": "File is required"
  }
}

Solutions:

Check request body format
Verify all required fields are present
Ensure file is properly attached
Validate parameter types

401 Unauthorized

Missing or invalid authentication credentials.Common Causes:

Missing Authorization header
Invalid API key or upload key
Expired token
Wrong key format

Example:

{
  "error": "Invalid or missing API key",
  "statusCode": 401
}

Solutions:

Include Authorization: Bearer YOUR_KEY header
Verify key starts with imperial_live_ or imperial_upload_
Generate new key if compromised
Check key hasn’t been revoked

403 Forbidden

Authenticated but lacking required permissions.Common Causes:

Upload key used for non-upload endpoints (Free/Starter)
Trying to access another user’s resources
Tier doesn’t support requested feature

Example:

{
  "error": "API access requires Pro or Business tier",
  "statusCode": 403
}

Solutions:

Upgrade to Pro/Business for full API access
Use correct authentication type for endpoint
Verify you own the resource you’re accessing

404 Not Found

The requested resource doesn’t exist.Common Causes:

Invalid image/upload ID
File was deleted
Typo in endpoint URL

Example:

{
  "error": "Image not found",
  "statusCode": 404
}

Solutions:

Verify resource ID is correct
Check if file was deleted
Ensure you own the resource
Verify endpoint URL is correct

413 Payload Too Large

File size or total request size exceeds limits.Common Causes:

Storage limit exceeded
File larger than available space
Batch upload too large

Example:

{
  "error": "Storage limit exceeded. You've used 4.8 GB of 5 GB.",
  "statusCode": 413
}

Solutions:

Delete old uploads to free space
Enable auto-compression
Upgrade to higher tier
Split large batch uploads

415 Unsupported Media Type

File type is not supported.Common Causes:

Uploading non-image/video files
Unsupported video codec
Corrupted file

Example:

{
  "error": "Only images and videos are allowed",
  "statusCode": 415
}

Solutions:

Use supported formats: JPEG, PNG, WebP, GIF, MP4, WebM, MOV, AVI
Verify file isn’t corrupted
Check MIME type is correct

429 Too Many Requests

Rate limit exceeded.Common Causes:

Too many requests per minute
Operations limit reached for month
Aggressive retry logic

Example:

{
  "error": "Rate limit exceeded. Try again in 42 seconds.",
  "statusCode": 429,
  "details": {
    "retryAfter": 42
  }
}

Solutions:

Respect Retry-After header
Implement exponential backoff
Reduce request frequency
Upgrade tier for higher rate limits

Server Error Codes (5xx)

500 Internal Server Error

An unexpected error occurred on the server.Common Causes:

Database connectivity issues
R2 storage unavailable
Unhandled exception

Example:

{
  "error": "An internal error occurred. Please try again.",
  "statusCode": 500
}

Solutions:

Retry the request after a delay
Check status page for incidents
Contact support if persistent
Implement retry logic with backoff

503 Service Unavailable

Service is temporarily unavailable.Common Causes:

Planned maintenance
Database migration
CDN issues

Example:

{
  "error": "Service temporarily unavailable",
  "statusCode": 503,
  "details": {
    "retryAfter": 300
  }
}

Solutions:

Wait and retry after specified time
Check status page for updates
Implement circuit breaker pattern

Common Error Scenarios

Authentication Errors

# ❌ Missing Authorization header
curl https://api.imperial.gay/images

# Error Response:

{
"error": "Authorization header is required",
"statusCode": 401
}

# ❌ Wrong key format
curl https://api.imperial.gay/images \
  -H "Authorization: imperial_live_xxxxx"

# Error Response:
{
  "error": "Authorization must use Bearer scheme",
  "statusCode": 401
}

# ✅ Correct format
curl https://api.imperial.gay/images \
  -H "Authorization: Bearer imperial_live_xxxxx"

Upload Errors

# Upload when storage full
curl -X POST https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@large.jpg"

# Error Response:

{
"error": "Storage limit exceeded. You've used 5.0 GB of 5 GB.",
"statusCode": 413
}

# Upload unsupported file
curl -X POST https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@document.pdf"

# Error Response:
{
  "error": "Only images and videos are allowed",
  "statusCode": 415
}

# Upload without file
curl -X POST https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer YOUR_KEY"

# Error Response:
{
  "error": "Validation failed",
  "statusCode": 400,
  "details": {
    "file": "File is required"
  }
}

Permission Errors

# Using upload key for listing (Free/Starter)
curl https://api.imperial.gay/images \
  -H "Authorization: Bearer imperial_upload_xxxxx"

# Error Response:

{
"error": "API access requires Pro or Business tier",
"statusCode": 403
}

# Trying to delete someone else's file
curl -X DELETE https://api.imperial.gay/images/abc123 \
  -H "Authorization: Bearer YOUR_KEY"

# Error Response:
{
  "error": "Image not found",
  "statusCode": 404
}

Rate Limiting

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1704643200

Header	Description
`X-RateLimit-Limit`	Max requests per window
`X-RateLimit-Remaining`	Requests left in window
`X-RateLimit-Reset`	Unix timestamp when limit resets

Handling Rate Limits

async function uploadWithRetry(file, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('https://api.imperial.gay/images/upload', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        },
        body: formData
      });
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        console.log(`Rate limited. Retrying in ${retryAfter}s...`);
        await sleep(retryAfter * 1000);
        continue;
      }
      
      return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000); // Exponential backoff
    }
  }
}

import time
import requests

def upload_with_retry(file_path, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                'https://api.imperial.gay/images/upload',
                headers={'Authorization': f'Bearer {API_KEY}'},
                files={'file': open(file_path, 'rb')}
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 60))
                print(f'Rate limited. Retrying in {retry_after}s...')
                time.sleep(retry_after)
                continue

            return response.json()
        except Exception as e:
            if attempt == max_retries - 1:
                raise e
            time.sleep(2 ** attempt)  # Exponential backoff

Best Practices

Error Handling

Check Status Code First

Use HTTP status code to determine error category (4xx vs 5xx)

Parse Error Message

Display error field to users for actionable feedback

Log Error Details

Store details object for debugging and support requests

Implement Retry Logic

Retry 5xx errors with exponential backoff. Don’t retry 4xx errors.

Retry Strategy

When to Retry: - ✅ 500 Internal Server Error - ✅ 503 Service Unavailable - ✅ 429 Rate Limited (with backoff) - ❌ 400-404 Client Errors (fix request instead)

Logging

Log these fields for troubleshooting:

{
  "timestamp": "2026-01-08T10:30:00Z",
  "endpoint": "POST /images/upload",
  "statusCode": 413,
  "error": "Storage limit exceeded",
  "requestId": "req_abc123",
  "userId": "user_xyz",
  "tier": "starter"
}

Testing Errors

Development Tips

# Test invalid API key
curl https://api.imperial.gay/images \
  -H "Authorization: Bearer invalid_key"

# Expected: 401 Unauthorized

# Make many rapid requests
for i in {1..100}; do
  curl https://api.imperial.gay/images \
    -H "Authorization: Bearer YOUR_KEY"
done

# Expected: 429 after limit exceeded

# Upload large file when near limit
curl -X POST https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@huge-file.mp4"

# Expected: 413 if exceeds remaining space

Get Help

Join Discord

Ask the community for help

Check Status

View API status and incidents

View Limits

Understand operations and storage

Upgrade Tier

Resolve limit-related errors

Getting Started

Guides

SDKs & Libraries

Reference

Key Features

Error Response Format

HTTP Status Codes

Success Codes

Client Error Codes (4xx)

Server Error Codes (5xx)

Common Error Scenarios

Authentication Errors

Upload Errors

Permission Errors

Rate Limiting

Rate Limit Headers

Handling Rate Limits

Best Practices

Error Handling

Retry Strategy

Logging

Testing Errors

Development Tips

Get Help

Join Discord

Check Status

View Limits

Upgrade Tier

​Error Response Format

​HTTP Status Codes

​Success Codes

​Client Error Codes (4xx)

​Server Error Codes (5xx)

​Common Error Scenarios

​Authentication Errors

​Upload Errors

​Permission Errors

​Rate Limiting

​Rate Limit Headers

​Handling Rate Limits

​Best Practices

​Error Handling

​Retry Strategy

​Logging

​Testing Errors

​Development Tips

​Get Help

Join Discord

Check Status

View Limits

Upgrade Tier

Error Response Format

HTTP Status Codes

Success Codes

Client Error Codes (4xx)

Server Error Codes (5xx)

Common Error Scenarios

Authentication Errors

Upload Errors

Permission Errors

Rate Limiting

Rate Limit Headers

Handling Rate Limits

Best Practices

Error Handling

Retry Strategy

Logging

Testing Errors

Development Tips

Get Help