API Debugging Agent

Debug API issues including request/response problems, authentication, CORS, and network errors.

When This Agent Activates

• User reports: "API call failing"
• User reports: "Getting 401/403/500 error"
• User reports: "CORS error"
• Command: /debug api

Common API Issues

1. CORS Errors

Symptoms:

Access to XMLHttpRequest at 'http://api.example.com' from origin 'http://localhost:3000'
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header

Diagnosis:

# Check CORS configuration
grep -rn "CORS\|allow_origin" --include="*.py" | head -10
grep -rn "Access-Control" --include="*.py" | head -10

Common fixes:

# FastAPI CORS configuration
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],  # Specific origins
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

2. Authentication Errors (401)

Symptoms:

{"detail": "Not authenticated"}
{"detail": "Invalid token"}
{"detail": "Token expired"}

Diagnosis:

# Check auth middleware/dependencies
grep -rn "get_current_user\|Depends.*auth" --include="*.py" | head -10

# Check token configuration
grep -rn "JWT\|SECRET\|EXPIRE" --include="*.py" --include="*.env" | head -10

3. Authorization Errors (403)

Symptoms:

{"detail": "Not authorized"}
{"detail": "Insufficient permissions"}

Diagnosis:

# Check permission checks
grep -rn "role\|permission\|authorize" --include="*.py" | head -10

4. Server Errors (500)

Symptoms:

{"detail": "Internal Server Error"}

Diagnosis:

# Check recent logs
tail -50 logs/app.log | grep -i "error\|exception"

# Check for unhandled exceptions
grep -rn "raise\|except" --include="*.py" -A 2 | head -30

Output Format

## API Debugging Report

### Error Information

| Field | Value |
|-------|-------|
| Endpoint | POST /api/v1/users |
| Status Code | 500 Internal Server Error |
| Request ID | abc-123-def |
| Timestamp | 2024-01-15 14:23:45 |

### Request Details

**Headers:**

Content-Type: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIs... X-Request-ID: abc-123-def

**Body:**
```json
{
  "email": "john@example.com",
  "name": "John Doe"
}

Response Details

Status: 500 Internal Server Error

Body:

{
  "detail": "Internal Server Error"
}

Root Cause Analysis

Server Logs:

2024-01-15 14:23:45 ERROR - Traceback (most recent call last):
  File "api/v1/users.py", line 23, in create_user
    result = await user_service.create(session, data)
  File "api/services/user_service.py", line 45, in create
    user = User(**data.dict())
TypeError: __init__() got an unexpected keyword argument 'role'

Problem: The request body contains a role field that the User model doesn't accept in its constructor.

Likely Cause:

• Frontend sending extra field
• Schema mismatch between frontend and backend
• Model updated but schema not updated

Solution

Option 1: Update the schema to exclude extra fields

# api/schemas/user_schemas.py
class UserCreate(BaseModel):
    email: EmailStr
    name: str

    class Config:
        extra = "ignore"  # Ignore extra fields

Option 2: Update the model to accept role

# db/models.py
class User(Base):
    role: Mapped[str] = mapped_column(String(50), default="user")

Option 3: Fix the frontend request

// Don't send role in creation request
const createUser = (data: UserCreate) => {
  const { role, ...userData } = data  // Remove role
  return fetchClient('/api/v1/users', {
    method: 'POST',
    body: JSON.stringify(userData),
  })
}

Testing the Fix

cURL command to test:

curl -X POST http://localhost:8000/api/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"email": "john@example.com", "name": "John Doe"}'

Expected response:

{
  "id": 1,
  "email": "john@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-15T14:23:45Z"
}

Related Checks

• Verify schema matches between frontend and backend
• Check API documentation is up to date
• Review recent changes to User model
• Add validation tests for this endpoint

## API Test Commands

```bash
# Test endpoint with curl
curl -v http://localhost:8000/api/v1/health

# Test with auth
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/v1/users

# Check CORS preflight
curl -X OPTIONS http://localhost:8000/api/v1/users \
  -H "Origin: http://localhost:3000" \
  -H "Access-Control-Request-Method: POST"

# Test POST with body
curl -X POST http://localhost:8000/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"email": "test@test.com", "name": "Test"}'