Error Handling

{
  "error": "error_code",
  "message": "Human-readable description",
  "details": {}
}

{
  "id": "gen_abc123",
  "status": "failed",
  "error": "Content policy violation: prohibited content detected"
}

{
  "status": "failed",
  "error": "Service unavailable: model is overloaded"
}

{
  "status": "failed", 
  "error": "Generation timeout: request deadline exceeded"
}

{
  "status": "failed",
  "error": "Content blocked by safety filter"
}

import requests

class ElumentaClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
    
    def request(self, method: str, path: str, **kwargs):
        headers = {"Authorization": f"Bearer {self.api_key}"}
        response = requests.request(
            method,
            f"https://elumenta.ru/api/v2{path}",
            headers=headers,
            **kwargs
        )
        
        if response.status_code == 401:
            # For API key auth, 401 means invalid key
            raise ValueError("Invalid API key")
        
        response.raise_for_status()
        return response.json()

{
  "error": "insufficient_tokens",
  "message": "Insufficient token balance. Required: 8, Available: 3",
  "details": {
    "required": 8,
    "available": 3
  }
}

try:
    result = client.generate_image(...)
except requests.HTTPError as e:
    if e.response.status_code == 402:
        print("Out of tokens! Top up at elumenta.ru/web/billing")

{
  "error": "rate_limit_exceeded",
  "message": "Hourly limit reached: 100 requests/hour",
  "retry_after": 847,
  "limit_hour": 100,
  "limit_day": 1000
}

{
  "error": "provider_error",
  "message": "Provider returned an error. No tokens were charged.",
  "provider": "openai"
}

import requests
import time
from typing import Optional

def make_request(
    url: str,
    headers: dict,
    payload: dict,
    max_retries: int = 3,
    retry_on: tuple = (429, 500, 503)
) -> Optional[dict]:
    
    for attempt in range(max_retries):
        try:
            res = requests.post(url, headers=headers, json=payload, timeout=60)
            
            if res.status_code in retry_on:
                if res.status_code == 429:
                    # Respect Retry-After header
                    wait = int(res.headers.get("Retry-After", 60))
                else:
                    # Exponential backoff for 5xx errors
                    wait = 2 ** attempt
                
                if attempt < max_retries - 1:
                    print(f"Attempt {attempt+1} failed ({res.status_code}), waiting {wait}s...")
                    time.sleep(wait)
                    continue
            
            res.raise_for_status()
            return res.json()
        
        except requests.Timeout:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise
    
    return None

def generate_with_error_handling(prompt: str):
    response = client.generate_image(prompt=prompt)
    
    if response.get("status") == "failed":
        error_msg = response.get("error", "Generation failed")
        
        # Handle specific error types
        if "overloaded" in error_msg.lower() or "503" in error_msg:
            print("Model is overloaded, try again later or use another model")
        elif "timeout" in error_msg.lower():
            print("Generation timed out, please retry")
        elif "content_policy" in error_msg.lower() or "safety" in error_msg.lower():
            print("Content blocked by moderation, please modify your prompt")
        else:
            print(f"Generation failed: {error_msg}")
        
        return None
    elif response.get("status") == "completed":
        return response.get("result_url")
    else:
        # Handle pending status for async operations
        return poll_generation(response.get("id"))

{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": {
    "fields": [
      {
        "field": "size",
        "message": "Value '512x512' is not valid for model dall-e-3. Valid sizes: 1024x1024, 1024x1792, 1792x1024"
      }
    ]
  }
}