🔍 HTTP Response Codes & Troubleshooting

#!/usr/bin/env python3
"""
Complete API Troubleshooting Example
Demonstrates how to debug and fix common API issues
"""

import requests
import json
import logging
from datetime import datetime

# Configure logging to see all request details
logging.basicConfig(level=logging.DEBUG)


class APITroubleshooter:
    """Helper class for troubleshooting API requests"""
    
    def __init__(self, base_url):
        self.base_url = base_url
        self.session = requests.Session()
    
    def diagnose_request(self, method, endpoint, **kwargs):
        """
        Make request and provide detailed diagnostic information
        """
        url = f"{self.base_url}{endpoint}"
        
        print("="*70)
        print(f"🔍 DIAGNOSING REQUEST")
        print("="*70)
        
        # Display request details
        print(f"\n📤 REQUEST DETAILS:")
        print(f"   Method:   {method}")
        print(f"   URL:      {url}")
        print(f"   Headers:  {json.dumps(kwargs.get('headers', {}), indent=13)}")
        
        if 'json' in kwargs:
            print(f"   Body:     {json.dumps(kwargs['json'], indent=13)}")
        
        try:
            # Make the request
            response = self.session.request(method, url, **kwargs)
            
            # Display response details
            print(f"\n📥 RESPONSE DETAILS:")
            print(f"   Status:   {response.status_code} {response.reason}")
            print(f"   Headers:  {json.dumps(dict(response.headers), indent=13)}")
            
            # Try to parse response body
            try:
                body = response.json()
                print(f"   Body:     {json.dumps(body, indent=13)}")
            except:
                print(f"   Body:     {response.text[:500]}")
            
            # Analyze the response
            print(f"\n🔍 ANALYSIS:")
            self._analyze_response(response, kwargs)
            
            return response
            
        except requests.exceptions.RequestException as e:
            print(f"\n❌ REQUEST FAILED: {e}")
            return None
    
    def _analyze_response(self, response, request_kwargs):
        """Analyze response and provide troubleshooting suggestions"""
        status = response.status_code
        
        if 200 <= status < 300:
            print("   ✅ SUCCESS - Request completed successfully")
            
        elif status == 400:
            print("   ❌ BAD REQUEST - Check request syntax and data")
            print("\n   Checklist:")
            print("   [ ] Is the JSON valid?")
            print("   [ ] Are all required fields present?")
            print("   [ ] Are data types correct?")
            print("   [ ] Is Content-Type header set?")
            
        elif status == 401:
            print("   ❌ UNAUTHORIZED - Authentication failed")
            print("\n   Checklist:")
            print("   [ ] Is Authorization header present?")
            print("   [ ] Is token format correct (Bearer )?")
            print("   [ ] Has the token expired?")
            print("   [ ] Is the token valid for this API?")
            
            headers = request_kwargs.get('headers', {})
            if 'Authorization' not in headers:
                print("\n   ⚠️  WARNING: No Authorization header found!")
            else:
                auth = headers['Authorization']
                if not auth.startswith('Bearer '):
                    print(f"\n   ⚠️  WARNING: Token might be missing 'Bearer' prefix")
                    
        elif status == 403:
            print("   ❌ FORBIDDEN - Insufficient permissions")
            print("\n   Checklist:")
            print("   [ ] Does your account have required permissions?")
            print("   [ ] Are you accessing your own resources?")
            print("   [ ] Does your plan/subscription support this?")
            print("   [ ] Is your IP address whitelisted?")
            
        elif status == 404:
            print("   ❌ NOT FOUND - Resource or endpoint doesn't exist")
            print("\n   Checklist:")
            print("   [ ] Is the URL correct?")
            print("   [ ] Is the API version correct?")
            print("   [ ] Does the resource ID exist?")
            print("   [ ] Are there any typos?")
            print("   [ ] Is there a trailing slash issue?")
            
        elif status == 422:
            print("   ❌ UNPROCESSABLE ENTITY - Validation failed")
            print("\n   Check response body for validation error details")
            
        elif status == 429:
            print("   ❌ TOO MANY REQUESTS - Rate limit exceeded")
            retry_after = response.headers.get('Retry-After')
            if retry_after:
                print(f"\n   ⏱️  Retry after: {retry_after} seconds")
            print("\n   Suggestions:")
            print("   • Add delays between requests")
            print("   • Implement exponential backoff")
            print("   • Use batch endpoints if available")
            print("   • Consider caching responses")
            
        elif 500 <= status < 600:
            print("   ❌ SERVER ERROR - Problem with API server")
            print("\n   Actions:")
            print("   • Check API status page")
            print("   • Wait and retry with exponential backoff")
            print("   • Contact API support if persists")
            print("   • Verify with minimal test request")


# =============================================================================
# DEMONSTRATION
# =============================================================================

if __name__ == "__main__":
    # Initialize troubleshooter
    troubleshooter = APITroubleshooter("https://jsonplaceholder.typicode.com")
    
    # Example 1: Successful request
    print("\n" + "🟢 EXAMPLE 1: Successful GET Request")
    troubleshooter.diagnose_request(
        "GET",
        "/posts/1"
    )
    
    input("\nPress Enter to continue to next example...")
    
    # Example 2: 404 Not Found
    print("\n" + "🔴 EXAMPLE 2: 404 Not Found")
    troubleshooter.diagnose_request(
        "GET",
        "/posts/99999"  # Non-existent resource
    )
    
    input("\nPress Enter to continue to next example...")
    
    # Example 3: Successful POST
    print("\n" + "🟢 EXAMPLE 3: Successful POST Request")
    troubleshooter.diagnose_request(
        "POST",
        "/posts",
        headers={"Content-Type": "application/json"},
        json={
            "title": "Test Post",
            "body": "This is a test",
            "userId": 1
        }
    )
    
    input("\nPress Enter to continue to next example...")
    
    # Example 4: Bad Request (simulated with GitHub API)
    print("\n" + "🔴 EXAMPLE 4: 401 Unauthorized")
    github_ts = APITroubleshooter("https://api.github.com")
    github_ts.diagnose_request(
        "GET",
        "/user",
        headers={"Authorization": "Bearer invalid_token_12345"}
    )