Error Handling

Reference for all error responses.

Error Response Format

All errors return JSON with this structure:

{
  "error": true,
  "message": "Human-readable error description",
  "code": "ERROR_CODE"
}

Error Codes Reference

Authentication Errors (401)

Code	Message	Solution
MISSING_API_KEY	Missing API key. Include X-API-Key header.	Add the X-API-Key header to your request
INVALID_API_KEY	Invalid API key.	Check your API key is correct

Authorization Errors (403)

Code	Message	Solution
SUBSCRIPTION_CANCELED	Your subscription has been canceled.	Resubscribe at the pricing page
PAYMENT_PAST_DUE	Your payment is past due.	Update payment method in billing portal

Validation Errors (400)

Code	Message	Solution
MISSING_TITLE	Missing required field: title	Include title in your request body
TITLE_TOO_LONG	Title must be 200 characters or less	Shorten your title
SUBTITLE_TOO_LONG	Subtitle must be 300 characters or less	Shorten your subtitle
INVALID_THEME	Invalid theme. Must be dark or light	Use "dark" or "light"
INVALID_TEMPLATE	Invalid template. Must be default, minimal, or vibrant	Use a valid template name
INVALID_AVATAR_URL	Invalid author_avatar_url. Must be a valid URL.	Provide a valid HTTPS URL
INVALID_JSON	Invalid JSON body	Check your JSON syntax

Rate Limit Errors (429)

Code	Message	Solution
QUOTA_EXCEEDED	Monthly quota exceeded. Limit: X images.	Upgrade plan or wait for monthly reset

Server Errors (500)

Code	Message	Solution
GENERATION_FAILED	Failed to generate image. Please try again.	Retry the request; contact support if persistent

Handling Errors

JavaScript/Node.js

async function generateImage(options) {
  const response = await fetch('https://ogimageapi.io/api/generate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.OG_IMAGE_API_KEY
    },
    body: JSON.stringify(options)
  });

  if (!response.ok) {
    const error = await response.json();
    
    switch (error.code) {
      case 'QUOTA_EXCEEDED':
        console.error('Quota exceeded - upgrade your plan');
        break;
      case 'INVALID_API_KEY':
        console.error('Check your API key');
        break;
      default:
        console.error(`Error: ${error.message}`);
    }
    
    throw new Error(error.message);
  }

  return response.arrayBuffer();
}

Python

import requests

def generate_image(options):
    response = requests.post(
        'https://ogimageapi.io/api/generate',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': os.environ.get('OG_IMAGE_API_KEY')
        },
        json=options
    )
    
    if not response.ok:
        error = response.json()
        
        if error.get('code') == 'QUOTA_EXCEEDED':
            raise QuotaExceededError(error['message'])
        elif error.get('code') == 'INVALID_API_KEY':
            raise AuthenticationError(error['message'])
        else:
            raise APIError(error['message'])
    
    return response.content

Retry Strategy

For transient errors (5xx), implement exponential backoff:

async function generateWithRetry(options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await generateImage(options);
    } catch (error) {
      if (error.status >= 500 && attempt < maxRetries - 1) {
        // Exponential backoff: 1s, 2s, 4s
        await sleep(1000 * Math.pow(2, attempt));
        continue;
      }
      throw error;
    }
  }
}

Getting Help

If you encounter persistent errors:

1. Check the FAQ for common issues
2. Verify your API key and plan status
3. Contact support with your error code and request details