{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": [
      {
        "field": "field_name",
        "issue": "SPECIFIC_ISSUE"
      }
    ],
    "trace_id": "a1b2c3d4e5f6",
    "timestamp": "2025-12-15T10:30:00Z"
  }
}

# LOS - Check API key format
headers = {"Authorization": api_key}  # No Bearer prefix

# LMS - Refresh expired token
token = refresh_jwt_token()
headers = {"Authorization": f"Bearer {token}"}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "trace_id": "a1b2c3d4e5"
  }
}

def refresh_token(client_id, client_secret):
    """Request new JWT token."""
    response = requests.post(
        "https://api.demo.lms.lendfoundry.com/oauth/token",
        data={
            "grant_type": "client_credentials",
            "client_id": client_id,
            "client_secret": client_secret
        }
    )
    return response.json()["access_token"]

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "JWT token expired at 2025-12-15T10:30:00Z",
    "details": "Request a new token from /oauth/token"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to access this resource",
    "details": "Your API key does not have access to this endpoint"
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request body is malformed",
    "details": [
      {
        "field": "loan_amount",
        "issue": "REQUIRED_FIELD_MISSING"
      },
      {
        "field": "interest_rate",
        "issue": "INVALID_TYPE",
        "expected": "number",
        "received": "string"
      }
    ]
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Loan amount cannot exceed maximum product limit",
    "details": [
      {
        "field": "loan_amount",
        "issue": "MAX_LIMIT_EXCEEDED",
        "max": 50000,
        "provided": 75000
      }
    ]
  }
}

{
  "error": {
    "code": "INVALID_DATE_FORMAT",
    "message": "Date must be in ISO 8601 format",
    "details": [
      {
        "field": "application_date",
        "issue": "INVALID_FORMAT",
        "expected": "YYYY-MM-DD",
        "received": "12/15/2025"
      }
    ]
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Loan with ID LN-2024-001234 not found",
    "details": {
      "resource_type": "loan",
      "resource_id": "LN-2024-001234"
    }
  }
}

{
  "error": {
    "code": "DUPLICATE_RESOURCE",
    "message": "Application with this borrower already exists",
    "details": {
      "resource_type": "application",
      "existing_id": "APP-2024-001234"
    }
  }
}

{
  "error": {
    "code": "BUSINESS_RULE_VIOLATION",
    "message": "Loan amount exceeds maximum product limit",
    "details": [
      {
        "rule": "LOAN_AMOUNT_EXCEEDS_LIMIT",
        "product_id": "PROD001",
        "max_amount": 50000,
        "requested_amount": 75000
      }
    ]
  }
}

{
  "error": {
    "code": "WORKFLOW_STATE_INVALID",
    "message": "Cannot fund application in current state",
    "details": {
      "current_state": "under_review",
      "requested_action": "fund",
      "valid_actions": ["approve", "decline"]
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 100,
      "remaining": 0,
      "reset_at": "2025-12-15T10:31:00Z",
      "retry_after": 60
    }
  }
}

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "trace_id": "a1b2c3d4e5f6",
    "details": "Please contact support with trace_id if issue persists"
  }
}

import requests
import time

class APIError(Exception):
    """Custom exception for API errors."""
    def __init__(self, code, message, details=None, trace_id=None):
        self.code = code
        self.message = message
        self.details = details
        self.trace_id = trace_id
        super().__init__(f"{code}: {message}")

def handle_response(response):
    """Handle API response and raise appropriate errors."""
    if response.status_code >= 400:
        error_data = response.json().get('error', {})
        
        raise APIError(
            code=error_data.get('code', 'UNKNOWN_ERROR'),
            message=error_data.get('message', 'Unknown error'),
            details=error_data.get('details'),
            trace_id=error_data.get('trace_id')
        )
    
    return response.json()

def make_request_with_retry(url, headers, data=None, max_retries=3):
    """Make request with comprehensive error handling."""
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=data, headers=headers)
            return handle_response(response)
            
        except APIError as e:
            # Handle specific error codes
            if e.code == 'RATE_LIMIT_EXCEEDED':
                retry_after = e.details.get('retry_after', 60) if e.details else 60
                time.sleep(retry_after)
                continue
            elif e.code == 'TOKEN_EXPIRED':
                # Refresh token and retry
                headers['Authorization'] = f"Bearer {refresh_token()}"
                continue
            elif e.code in ['INTERNAL_SERVER_ERROR', 'SERVICE_UNAVAILABLE']:
                # Exponential backoff for server errors
                time.sleep(2 ** attempt)
                continue
            else:
                # Non-retryable error
                raise
                
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    
    raise Exception("Max retries exceeded")