Skip to main content
Learn how to handle errors gracefully and build robust applications with the Gravix Layer SDK.

​
Common Error Types

The SDK provides specific exceptions for different scenarios: 
from gravixlayer.exceptions import (
    GravixLayerError,        # Base exception
    AuthenticationError,     # Invalid API key
    RateLimitError,         # Rate limit exceeded
    APIError,               # General API errors
    ValidationError,        # Request validation errors
    TimeoutError           # Request timeout
)

​
Basic Error Handling

Always wrap API calls in try-catch blocks: 
from gravixlayer import GravixLayer
from gravixlayer.exceptions import GravixLayerError

client = GravixLayer()

try:
    response = client.chat.completions.create(
        model="meta-llama/llama-3.1-8b-instruct",
        messages=[{"role": "user", "content": "Hello"}]
    )
    print(response.choices[0].message.content)
except GravixLayerError as e:
    print(f"API Error: {e}")

​
Retry Logic with Backoff

Handle transient errors with exponential backoff: 
import time
from gravixlayer import GravixLayer
from gravixlayer.exceptions import RateLimitError, TimeoutError

def make_request_with_retry(messages, max_retries=3):
    client = GravixLayer()
    
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="meta-llama/llama-3.1-8b-instruct",
                messages=messages
            )
        
        except RateLimitError:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Rate limit hit. Retrying in {wait_time} seconds...")
                time.sleep(wait_time)
            else:
                print("Rate limit exceeded. Max retries reached.")
                raise
        
        except TimeoutError:
            if attempt < max_retries - 1:
                print(f"Request timeout. Retrying... (attempt {attempt + 1})")
            else:
                print("Request timeout. Max retries reached.")
                raise

# Usage
try:
    response = make_request_with_retry([
        {"role": "user", "content": "Hello!"}
    ])
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Failed after all retries: {e}")

​
Handling Specific Errors

Handle different error types with specific actions: 
from gravixlayer import GravixLayer
from gravixlayer.exceptions import (
    AuthenticationError,
    RateLimitError,
    ValidationError
)

client = GravixLayer()

try:
    response = client.chat.completions.create(
        model="meta-llama/llama-3.1-8b-instruct",
        messages=[{"role": "user", "content": "Hello"}]
    )
    print(response.choices[0].message.content)

except AuthenticationError:
    print("❌ Invalid API key. Please check your credentials.")

except RateLimitError as e:
    print(f"⏳ Rate limit exceeded. Try again later: {e}")

except ValidationError as e:
    print(f"📝 Invalid request parameters: {e}")

except Exception as e:
    print(f"💥 Unexpected error: {e}")

​
Async Error Handling

Error handling works the same with async methods: 
import asyncio
from gravixlayer import AsyncGravixLayer
from gravixlayer.exceptions import GravixLayerError

async def safe_async_request():
    async with AsyncGravixLayer() as client:
        try:
            response = await client.chat.completions.create(
                model="meta-llama/llama-3.1-8b-instruct",
                messages=[{"role": "user", "content": "Hello"}]
            )
            return response.choices[0].message.content
        except GravixLayerError as e:
            print(f"Async API Error: {e}")
            return None

result = asyncio.run(safe_async_request())

​
Production-Ready Error Handler

A comprehensive error handler for production applications: 
import logging
import time
from gravixlayer import GravixLayer
from gravixlayer.exceptions import (
    AuthenticationError,
    RateLimitError,
    ValidationError,
    TimeoutError,
    GravixLayerError
)

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class RobustClient:
    def __init__(self, max_retries=3, base_delay=1):
        self.client = GravixLayer()
        self.max_retries = max_retries
        self.base_delay = base_delay
    
    def chat_completion(self, messages, model="meta-llama/llama-3.1-8b-instruct"):
        """Make a chat completion request with robust error handling."""
        
        for attempt in range(self.max_retries):
            try:
                response = self.client.chat.completions.create(
                    model=model,
                    messages=messages
                )
                logger.info(f"✅ Request successful on attempt {attempt + 1}")
                return response
            
            except AuthenticationError as e:
                logger.error(f"❌ Authentication failed: {e}")
                raise  # Don't retry auth errors
            
            except ValidationError as e:
                logger.error(f"📝 Invalid request: {e}")
                raise  # Don't retry validation errors
            
            except RateLimitError as e:
                if attempt < self.max_retries - 1:
                    delay = self.base_delay * (2 ** attempt)
                    logger.warning(f"⏳ Rate limited. Retrying in {delay}s: {e}")
                    time.sleep(delay)
                else:
                    logger.error(f"❌ Rate limit exceeded after {self.max_retries} attempts")
                    raise
            
            except TimeoutError as e:
                if attempt < self.max_retries - 1:
                    delay = self.base_delay * (attempt + 1)
                    logger.warning(f"⏱️ Timeout. Retrying in {delay}s: {e}")
                    time.sleep(delay)
                else:
                    logger.error(f"❌ Timeout after {self.max_retries} attempts")
                    raise
            
            except GravixLayerError as e:
                logger.error(f"💥 API error: {e}")
                if attempt < self.max_retries - 1:
                    delay = self.base_delay * (attempt + 1)
                    logger.info(f"🔄 Retrying in {delay}s...")
                    time.sleep(delay)
                else:
                    raise

# Usage
client = RobustClient()

try:
    response = client.chat_completion([
        {"role": "user", "content": "Hello!"}
    ])
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Request failed: {e}")

​
Best Practices

  1. Always use try-catch for API calls
  2. Implement exponential backoff for rate limits
  3. Log errors appropriately for debugging
  4. Don’t retry authentication errors - fix the API key instead
  5. Set reasonable timeouts to prevent hanging requests
  6. Handle specific error types differently based on your use case
⌘I