Error Handling

Learn how to handle errors from the Creed Space API.

Error Response Format

All errors follow a consistent format:

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

Error Codes

Authentication Errors (4xx)

Code	Error	Description
401	api_key_required	No API key provided
401	invalid_api_key	Key is invalid or revoked
401	expired_api_key	Key has expired
403	insufficient_scope	Key lacks required permission
403	ip_not_allowed	Request IP not in whitelist

Validation Errors (400)

Error	Description
validation_error	Request body validation failed
invalid_json	Request body is not valid JSON
missing_field	Required field is missing

Rate Limiting (429)

Error	Description
rate_limit_exceeded	Per-minute limit exceeded
daily_limit_exceeded	Per-day limit exceeded

Server Errors (5xx)

Code	Error	Description
500	internal_error	Unexpected server error
503	service_unavailable	Service temporarily unavailable

Handling Errors

Python

from creed_sdk import CreedSpace
from creed_sdk.exceptions import (
    CreedSpaceError,
    AuthenticationError,
    RateLimitError,
    ValidationError
)

client = CreedSpace(api_key="...")

try:
    result = client.safety.evaluate(text)
except AuthenticationError as e:
    # Invalid or missing API key
    logger.error(f"Auth failed: {e}")
    raise HTTPException(401, "API key error")

except RateLimitError as e:
    # Rate limited - wait and retry
    logger.warning(f"Rate limited, retry after {e.retry_after}s")
    time.sleep(e.retry_after)
    result = client.safety.evaluate(text)

except ValidationError as e:
    # Invalid request
    logger.error(f"Validation failed: {e.details}")
    raise HTTPException(400, "Invalid request")

except CreedSpaceError as e:
    # Other API errors
    logger.error(f"API error: {e}")
    raise HTTPException(500, "Safety check failed")

JavaScript

import {
    CreedSpace,
    CreedSpaceError,
    AuthenticationError,
    RateLimitError,
    ValidationError
} from '@creed-space/sdk';

const client = new CreedSpace({ apiKey: '...' });

try {
    const result = await client.safety.evaluate(text);
} catch (error) {
    if (error instanceof AuthenticationError) {
        console.error('Auth failed:', error.message);
        throw new Error('API key error');
    }

    if (error instanceof RateLimitError) {
        console.warn(`Rate limited, retry after ${error.retryAfter}s`);
        await sleep(error.retryAfter * 1000);
        return client.safety.evaluate(text);
    }

    if (error instanceof ValidationError) {
        console.error('Validation failed:', error.details);
        throw new Error('Invalid request');
    }

    if (error instanceof CreedSpaceError) {
        console.error('API error:', error.message);
        throw new Error('Safety check failed');
    }

    throw error;
}

Retry Strategies

Simple Retry

def evaluate_with_retry(text, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.safety.evaluate(text)
        except (RateLimitError, CreedSpaceError) as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(1 * (attempt + 1))

Circuit Breaker

For production systems, use a circuit breaker pattern:

from circuitbreaker import circuit

@circuit(failure_threshold=5, recovery_timeout=30)
def evaluate_safe(text):
    return client.safety.evaluate(text)

Debugging

Enable Logging

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('creed_sdk')
logger.setLevel(logging.DEBUG)

Check Response Headers

try:
    result = client.safety.evaluate(text)
except CreedSpaceError as e:
    print(f"Request ID: {e.request_id}")
    print(f"Status: {e.status_code}")

Getting Help

If you encounter persistent errors:

1. Check API Status
2. Include the request ID when contacting support
3. Review your Dashboard for usage issues