Error Handling

The Orcho Risk Generation API uses standard HTTP status codes and provides detailed error information to help you diagnose and resolve issues quickly.

Error Response Format

All error responses follow a consistent structure:

{
  "success": false,
  "error": "Human-readable error message",
  "error_code": "HTTP_XXX",
  "details": {
    "status_code": 400,
    "additional_context": "..."
  }
}

success

boolean

Always false for error responses

error

string

Human-readable description of what went wrong

error_code

string

Machine-readable error code (format: HTTP_XXX)

details

object

Additional context about the error, including the HTTP status code and other relevant information

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:

Status Code	Meaning	When It Occurs
200	Success	Request processed successfully
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid key but insufficient permissions
404	Not Found	Resource doesn’t exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
503	Service Unavailable	API temporarily unavailable

Common Errors

400 Bad Request

The request contains invalid data or missing required fields.

Missing Required Fields

Error:

{
  "success": false,
  "error": "Prompt is required and cannot be empty",
  "error_code": "HTTP_400",
  "details": {
    "status_code": 400
  }
}

Cause: The prompt field is missing or empty.Solution:

# ❌ Missing prompt
data = {}

# ✅ Include prompt
data = {
    "prompt": "Your task description here"
}

Invalid Weight Configuration

Error:

{
  "success": false,
  "error": "Weights must sum to 1.0",
  "error_code": "HTTP_400",
  "details": {
    "status_code": 400,
    "provided_sum": 0.85
  }
}

Cause: Custom weights don’t sum to 1.0.Solution:

# ❌ Invalid weights (sum = 0.85)
weights = {
    "data_sensitivity": 0.2,
    "input_clarity": 0.15,
    "blast_radius": 0.2,
    "context_complexity": 0.15,
    "legal_ip_risk": 0.15
    # Missing model_hallucination
}

# ✅ Valid weights (sum = 1.0)
weights = {
    "data_sensitivity": 0.2,
    "input_clarity": 0.15,
    "blast_radius": 0.2,
    "context_complexity": 0.15,
    "legal_ip_risk": 0.15,
    "model_hallucination": 0.15
}

Invalid Context Format

Error:

{
  "success": false,
  "error": "Invalid repository format. Use 'owner/repo'",
  "error_code": "HTTP_400",
  "details": {
    "status_code": 400,
    "provided": "myrepo"
  }
}

Cause: Repository name isn’t in owner/repo format.Solution:

# ❌ Invalid format
context = {
    "repo_full_name": "myrepo",
    "current_file": "src/main.py"
}

# ✅ Correct format
context = {
    "repo_full_name": "mycompany/myrepo",
    "current_file": "src/main.py"
}

401 Unauthorized

Authentication failed or API key is invalid.

Missing API Key

Error:

{
  "success": false,
  "error": "API key is required",
  "error_code": "HTTP_401",
  "details": {
    "status_code": 401
  }
}

Cause: No Authorization header provided.Solution:

# ❌ Missing authorization
headers = {
    'Content-Type': 'application/json'
}

# ✅ Include authorization
headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

Invalid API Key

Error:

{
  "success": false,
  "error": "Invalid API key",
  "error_code": "HTTP_401",
  "details": {
    "status_code": 401
  }
}

Cause: API key is incorrect, expired, or revoked.Solution:

Verify your API key in the dashboard
Generate a new key if the current one is expired
Check for typos or extra whitespace in the key

Malformed Authorization Header

Error:

{
  "success": false,
  "error": "Authorization header must be 'Bearer YOUR_API_KEY'",
  "error_code": "HTTP_401",
  "details": {
    "status_code": 401
  }
}

Cause: Authorization header format is incorrect.Solution:

# ❌ Incorrect format
headers = {
    'Authorization': f'{API_KEY}'  # Missing "Bearer"
}

# ❌ Incorrect format
headers = {
    'Authorization': f'Token {API_KEY}'  # Wrong prefix
}

# ✅ Correct format
headers = {
    'Authorization': f'Bearer {API_KEY}'
}

429 Rate Limit Exceeded

You’ve exceeded the API rate limits. Error:

{
  "success": false,
  "error": "Rate limit exceeded",
  "error_code": "HTTP_429",
  "details": {
    "status_code": 429,
    "retry_after": 60,
    "limit": "100 requests per minute"
  }
}

Cause: Too many requests in a short time period. Solution: Implement exponential backoff and respect rate limits.

import time
import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

def create_session_with_retries():
    """Create session with automatic retry logic"""
    session = requests.Session()
    
    retry_strategy = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504],
        allowed_methods=["POST", "GET"]
    )
    
    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("https://", adapter)
    
    return session

# Use the session
session = create_session_with_retries()
response = session.post(
    'https://app.orcho.ai/api/v1/generate-risk',
    headers=headers,
    json=data
)

Contact [email protected] to discuss higher rate limits for enterprise usage.

500 Internal Server Error

A server-side error occurred. Error:

{
  "success": false,
  "error": "Internal server error",
  "error_code": "INTERNAL_ERROR",
  "details": {
    "status_code": 500,
    "exception": "Unexpected error during risk calculation"
  }
}

Cause: Server encountered an unexpected error. Solution:

Retry the request after a brief delay
Check API status at status.orcho.ai
Contact support if the issue persists
Include the error details and timestamp when reporting

Error Handling Best Practices

Always check the success field

Never assume a request succeeded. Always verify the success field:

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result.get('success'):
    # Process successful response
    risk_score = result['overall_score']
else:
    # Handle error
    error_msg = result.get('error', 'Unknown error')
    logging.error(f"Risk assessment failed: {error_msg}")

Implement proper exception handling

Wrap API calls in try-except blocks:

try:
    response = requests.post(url, headers=headers, json=data, timeout=30)
    response.raise_for_status()
    result = response.json()
    
    if not result.get('success'):
        handle_api_error(result)
    
    return result
    
except requests.exceptions.Timeout:
    # Handle timeout
    logging.error("Request timed out")
    
except requests.exceptions.ConnectionError:
    # Handle connection errors
    logging.error("Connection failed")
    
except requests.exceptions.HTTPError as e:
    # Handle HTTP errors
    logging.error(f"HTTP error: {e.response.status_code}")
    
except Exception as e:
    # Handle unexpected errors
    logging.error(f"Unexpected error: {str(e)}")

Log errors with context

Include relevant context when logging errors:

def assess_risk(prompt, context=None):
    try:
        response = make_api_request(prompt, context)
        return response
    except Exception as e:
        logging.error(
            "Risk assessment failed",
            extra={
                'prompt_length': len(prompt),
                'has_context': context is not None,
                'error': str(e),
                'timestamp': datetime.now().isoformat()
            }
        )
        raise

Provide fallback behavior

Handle errors gracefully with sensible defaults:

def get_risk_score(prompt, default_score=50):
    """Get risk score with fallback to default"""
    try:
        result = assess_risk(prompt)
        return result['overall_score']
    except Exception as e:
        logging.warning(f"Using default risk score due to error: {e}")
        return default_score

Validation Errors

Input validation errors provide specific details about what’s wrong:

{
  "success": false,
  "error": "Prompt must be a string",
  "error_code": "HTTP_400",
  "details": {
    "status_code": 400,
    "field": "prompt",
    "expected_type": "string",
    "received_type": "object"
  }
}

Testing Error Handling

Test your error handling with these scenarios:

def test_invalid_api_key():
    """Test behavior with invalid API key"""
    headers = {
        'Authorization': 'Bearer INVALID_KEY',
        'Content-Type': 'application/json'
    }
    
    response = requests.post(url, headers=headers, json=data)
    
    assert response.status_code == 401
    assert response.json()['success'] is False
    assert 'Invalid API key' in response.json()['error']

Monitoring and Alerting

Set up monitoring to catch errors before they become problems:

import logging
from datetime import datetime

class APIErrorMonitor:
    def __init__(self):
        self.error_count = {}
        self.alert_threshold = 10
    
    def log_error(self, error_code, details):
        """Log error and trigger alerts if threshold exceeded"""
        timestamp = datetime.now().isoformat()
        
        # Increment error counter
        self.error_count[error_code] = self.error_count.get(error_code, 0) + 1
        
        # Log the error
        logging.error(
            f"API Error: {error_code}",
            extra={
                'error_code': error_code,
                'details': details,
                'timestamp': timestamp,
                'total_count': self.error_count[error_code]
            }
        )
        
        # Check if alert threshold exceeded
        if self.error_count[error_code] >= self.alert_threshold:
            self.send_alert(error_code, self.error_count[error_code])
    
    def send_alert(self, error_code, count):
        """Send alert when error threshold exceeded"""
        message = f"API error threshold exceeded: {error_code} occurred {count} times"
        # Send to your alerting system (Slack, PagerDuty, etc.)
        logging.critical(message)

# Use the monitor
monitor = APIErrorMonitor()

try:
    result = assess_risk(prompt)
except Exception as e:
    monitor.log_error('ASSESSMENT_FAILED', str(e))

Support

If you encounter persistent errors or need help troubleshooting:

Check API Status

View current API status and incidents

Email Support

Contact [email protected]

Documentation

Review API documentation

GitHub Issues

Report bugs and issues

When contacting support, include the error message, error code, timestamp, and any relevant request details to help us assist you faster.

Email Support

Getting Started

Risk Assessment Endpoints

Resources

Error Handling

Error Response Format

HTTP Status Codes

Common Errors

400 Bad Request

401 Unauthorized

429 Rate Limit Exceeded

500 Internal Server Error

Error Handling Best Practices

Validation Errors

Testing Error Handling

Monitoring and Alerting

Support

Check API Status

Documentation

GitHub Issues

Getting Started

Risk Assessment Endpoints

Resources

​Error Response Format

​HTTP Status Codes

​Common Errors

​400 Bad Request

​401 Unauthorized

​429 Rate Limit Exceeded

​500 Internal Server Error

​Error Handling Best Practices

​Validation Errors

​Testing Error Handling

​Monitoring and Alerting

​Support

Check API Status

Email Support

Documentation

GitHub Issues

Error Response Format

HTTP Status Codes

Common Errors

400 Bad Request

401 Unauthorized

429 Rate Limit Exceeded

500 Internal Server Error

Error Handling Best Practices

Validation Errors

Testing Error Handling

Monitoring and Alerting

Support