Error Handling

Understanding API errors, status codes, and how to handle them in your application. All errors follow a consistent format for easy parsing and handling.

Error Response Format

All error responses follow a consistent JSON structure with an error object:

Error Response Structure

{
  "error": {
    "message": "Human-readable error message",
    "code": "ERROR_CODE",
    "statusCode": 400
  }
}

message

Human-readable description of the error

code

Machine-readable error identifier (optional)

statusCode

HTTP status code of the error

HTTP Status Codes

400

Bad Request

VALIDATION_ERROR

The request body contains invalid data or missing required fields.

Common Causes:

• Invalid URL format
• Missing required parameters
• Invalid parameter values (e.g., viewport_width out of range)
• Malformed JSON in request body

401

Unauthorized

UNAUTHORIZED

Authentication failed or API key is missing/invalid.

Common Causes:

• Missing Authorization header
• Invalid API key format
• Expired or revoked API key
• API key belongs to different user

403

Forbidden

FORBIDDEN

You don't have permission to access this resource.

Common Causes:

• Trying to access another user's screenshot
• Trying to delete another user's API key
• Insufficient permissions for the operation

404

Not Found

NOT_FOUND

The requested resource doesn't exist.

Common Causes:

• Screenshot ID doesn't exist
• API key ID doesn't exist
• Resource was already deleted
• Invalid endpoint URL

429

Too Many Requests

RATE_LIMIT_EXCEEDED / USAGE_LIMIT_EXCEEDED

Rate limit or usage quota exceeded.

Common Causes:

• Too many requests in short time period (rate limit)
• Monthly screenshot quota exhausted (usage limit)
• Batch request exceeds remaining quota

500

Internal Server Error

An unexpected error occurred on our servers.

Common Causes:

• Database connection issues
• Queue system failures
• Storage service unavailable
• Unexpected server error

Error Examples

401 Unauthorized

json

{
  "error": {
    "message": "Unauthorized",
    "code": "UNAUTHORIZED",
    "statusCode": 401
  }
}

400 Validation Error

json

{
  "error": {
    "message": "Validation failed: Invalid URL format",
    "code": "VALIDATION_ERROR",
    "statusCode": 400
  }
}

429 Usage Limit Exceeded

json

{
  "error": {
    "message": "Monthly usage limit reached. Upgrade your plan to continue.",
    "code": "USAGE_LIMIT_EXCEEDED",
    "statusCode": 429
  }
}

404 Not Found

json

{
  "error": {
    "message": "Screenshot not found",
    "code": "NOT_FOUND",
    "statusCode": 404
  }
}

Handling Errors in Code

JavaScript / Node.js

javascript

async function captureScreenshot(url) {
  try {
    const response = await fetch('https://www.snapshotai.dev/api/v1/screenshots', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ url })
    });

    if (!response.ok) {
      const error = await response.json();
      
      // Handle specific error codes
      switch (error.error.code) {
        case 'UNAUTHORIZED':
          console.error('Invalid API key');
          break;
        case 'USAGE_LIMIT_EXCEEDED':
          console.error('Monthly quota exceeded');
          break;
        case 'VALIDATION_ERROR':
          console.error('Invalid URL:', error.error.message);
          break;
        default:
          console.error('API error:', error.error.message);
      }
      
      throw new Error(error.error.message);
    }

    return await response.json();
  } catch (error) {
    console.error('Failed to capture screenshot:', error);
    throw error;
  }
}

Python

python

import requests
from requests.exceptions import HTTPError

def capture_screenshot(url):
    try:
        response = requests.post(
            'https://www.snapshotai.dev/api/v1/screenshots',
            headers={
                'Authorization': 'Bearer YOUR_API_KEY',
                'Content-Type': 'application/json'
            },
            json={'url': url}
        )
        
        response.raise_for_status()
        return response.json()
        
    except HTTPError as e:
        error_data = e.response.json()
        error_code = error_data.get('error', {}).get('code')
        error_message = error_data.get('error', {}).get('message')
        
        # Handle specific error codes
        if error_code == 'UNAUTHORIZED':
            print('Invalid API key')
        elif error_code == 'USAGE_LIMIT_EXCEEDED':
            print('Monthly quota exceeded')
        elif error_code == 'VALIDATION_ERROR':
            print(f'Validation error: {error_message}')
        else:
            print(f'API error: {error_message}')
        
        raise
    except Exception as e:
        print(f'Failed to capture screenshot: {str(e)}')
        raise

Best Practices

• Always check HTTP status before parsing response
• Use error codes for programmatic error handling, not messages
• Log errors with full context for debugging
• Implement retries with exponential backoff for 5xx errors
• Handle 429 errors by respecting rate limits and upgrading if needed
• Validate input on client side to avoid 400 errors

Retry Strategy

• Do retry: 500, 502, 503, 504 errors (server issues)
• Don't retry: 400, 401, 403, 404 errors (client errors)
• Be careful with 429: Respect retry-after header if provided
• Use exponential backoff: Wait 1s, 2s, 4s, 8s between retries
• Limit retries: Maximum 3-5 attempts before failing

Need Help?

If you're experiencing persistent errors or need help debugging, contact our support team with:

• The error message and code
• Your request payload (without sensitive data)
• Screenshot ID or timestamp of the error
• Your API key prefix (never send the full key)

Contact Support →

Error Response Format

All error responses follow a consistent JSON structure with an error object:

Error Response Structure

{
  "error": {
    "message": "Human-readable error message",
    "code": "ERROR_CODE",
    "statusCode": 400
  }
}

message

Human-readable description of the error

code

Machine-readable error identifier (optional)

statusCode

HTTP status code of the error

HTTP Status Codes

400

Bad Request

VALIDATION_ERROR

The request body contains invalid data or missing required fields.

Common Causes:

• Invalid URL format
• Missing required parameters
• Invalid parameter values (e.g., viewport_width out of range)
• Malformed JSON in request body

401

Unauthorized

UNAUTHORIZED

Authentication failed or API key is missing/invalid.

Common Causes:

• Missing Authorization header
• Invalid API key format
• Expired or revoked API key
• API key belongs to different user

403

Forbidden

FORBIDDEN

You don't have permission to access this resource.

Common Causes:

• Trying to access another user's screenshot
• Trying to delete another user's API key
• Insufficient permissions for the operation

404

Not Found

NOT_FOUND

The requested resource doesn't exist.

Common Causes:

• Screenshot ID doesn't exist
• API key ID doesn't exist
• Resource was already deleted
• Invalid endpoint URL

429

Too Many Requests

RATE_LIMIT_EXCEEDED / USAGE_LIMIT_EXCEEDED

Rate limit or usage quota exceeded.

Common Causes:

• Too many requests in short time period (rate limit)
• Monthly screenshot quota exhausted (usage limit)
• Batch request exceeds remaining quota

500

Internal Server Error

An unexpected error occurred on our servers.

Common Causes:

• Database connection issues
• Queue system failures
• Storage service unavailable
• Unexpected server error

Error Examples

401 Unauthorized

json

{
  "error": {
    "message": "Unauthorized",
    "code": "UNAUTHORIZED",
    "statusCode": 401
  }
}

400 Validation Error

json

{
  "error": {
    "message": "Validation failed: Invalid URL format",
    "code": "VALIDATION_ERROR",
    "statusCode": 400
  }
}

429 Usage Limit Exceeded

json

{
  "error": {
    "message": "Monthly usage limit reached. Upgrade your plan to continue.",
    "code": "USAGE_LIMIT_EXCEEDED",
    "statusCode": 429
  }
}

404 Not Found

json

{
  "error": {
    "message": "Screenshot not found",
    "code": "NOT_FOUND",
    "statusCode": 404
  }
}

Handling Errors in Code

JavaScript / Node.js

javascript

async function captureScreenshot(url) {
  try {
    const response = await fetch('https://www.snapshotai.dev/api/v1/screenshots', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ url })
    });

    if (!response.ok) {
      const error = await response.json();
      
      // Handle specific error codes
      switch (error.error.code) {
        case 'UNAUTHORIZED':
          console.error('Invalid API key');
          break;
        case 'USAGE_LIMIT_EXCEEDED':
          console.error('Monthly quota exceeded');
          break;
        case 'VALIDATION_ERROR':
          console.error('Invalid URL:', error.error.message);
          break;
        default:
          console.error('API error:', error.error.message);
      }
      
      throw new Error(error.error.message);
    }

    return await response.json();
  } catch (error) {
    console.error('Failed to capture screenshot:', error);
    throw error;
  }
}

Python

python

import requests
from requests.exceptions import HTTPError

def capture_screenshot(url):
    try:
        response = requests.post(
            'https://www.snapshotai.dev/api/v1/screenshots',
            headers={
                'Authorization': 'Bearer YOUR_API_KEY',
                'Content-Type': 'application/json'
            },
            json={'url': url}
        )
        
        response.raise_for_status()
        return response.json()
        
    except HTTPError as e:
        error_data = e.response.json()
        error_code = error_data.get('error', {}).get('code')
        error_message = error_data.get('error', {}).get('message')
        
        # Handle specific error codes
        if error_code == 'UNAUTHORIZED':
            print('Invalid API key')
        elif error_code == 'USAGE_LIMIT_EXCEEDED':
            print('Monthly quota exceeded')
        elif error_code == 'VALIDATION_ERROR':
            print(f'Validation error: {error_message}')
        else:
            print(f'API error: {error_message}')
        
        raise
    except Exception as e:
        print(f'Failed to capture screenshot: {str(e)}')
        raise