🔍 API Debugging

Troubleshoot REST API issues in SEA™ services.

Request Tracing

Using X-Request-Id

Every request should include a correlation ID:

1
2
3

curl -v \
  -H "X-Request-Id: debug-$(uuidgen)" \
  http://localhost:8000/api/v1/cases

Find Request in Logs

1
2
3
4
5

# Search logs by request ID
docker logs sea-api 2>&1 | grep "debug-abc123"

# Or in OpenObserve
# Query: request_id="debug-abc123"

Common Issues

400 Bad Request

Cause: Invalid input data

1
2
3
4
5
6
7
8
9
10
11
12

# Check request body
curl -v -X POST http://localhost:8000/api/v1/cases \
  -H "Content-Type: application/json" \
  -d '{"title": ""}' 

# Response shows validation errors
{
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [{"field": "title", "code": "REQUIRED"}]
  }
}

401 Unauthorized

Cause: Missing or invalid token

1
2
3
4
5
6

# Check token is present
curl -v http://localhost:8000/api/v1/cases \
  -H "Authorization: Bearer $TOKEN"

# Decode JWT to check expiry
echo $TOKEN | cut -d. -f2 | base64 -d | jq

403 Forbidden

Cause: Insufficient permissions

1
2
3
4
5

# Check user roles in token
echo $TOKEN | cut -d. -f2 | base64 -d | jq '.roles'

# Compare with required permissions in logs
docker logs sea-api 2>&1 | grep "permission denied"

404 Not Found

Cause: Resource doesn’t exist or wrong URL

1
2
3
4
5

# Verify resource exists
psql $DATABASE_URL -c "SELECT id FROM cases WHERE id = 'case-123';"

# Check URL pattern matches routes
curl http://localhost:8000/openapi.json | jq '.paths | keys'

429 Rate Limited

Cause: Too many requests

1
2
3
4
5

# Check rate limit headers
curl -v http://localhost:8000/api/v1/cases 2>&1 | grep -i rate

# Wait for reset
X-RateLimit-Reset: 1704067200

500 Internal Error

Cause: Server-side exception

1
2
3
4
5

# Check application logs
docker logs sea-api --tail 100 | grep -A 10 "error"

# Check for stack trace
docker logs sea-api 2>&1 | grep -A 20 "Traceback"

Performance Debugging

Slow Requests

1
2
3
4
5
6
7
8

# Enable timing
curl -o /dev/null -s -w "\
DNS: %{time_namelookup}s\n\
Connect: %{time_connect}s\n\
TLS: %{time_appconnect}s\n\
Start: %{time_starttransfer}s\n\
Total: %{time_total}s\n" \
http://localhost:8000/api/v1/cases

Database Query Analysis

1
2
3
4
5
6

-- Find slow queries
SELECT query, calls, mean_time, total_time
FROM pg_stat_statements
WHERE mean_time > 100  -- ms
ORDER BY total_time DESC
LIMIT 10;

OpenAPI Validation

1
2
3
4
5

# Download spec
curl http://localhost:8000/openapi.json > openapi.json

# Validate request matches spec
# Use tools like openapi-spec-validator

Debugging Tools

Tool Purpose
curl -v HTTP request details
jq JSON parsing
httpie User-friendly HTTP client
VS Code REST Client IDE integration