# Troubleshooting Guide

Quick reference for diagnosing common problems.

## Quick Checklist

- [ ] Is the service up? (Health check endpoint)
- [ ] Are credentials valid? (Try different token)
- [ ] Is endpoint correct? (Check URL spelling)
- [ ] Is request format correct? (Validate JSON)
- [ ] Are you rate limited? (Check rate limit headers)
- [ ] Is network connectivity OK? (Ping service)
- [ ] Have you checked logs? (Search for request ID)
- [ ] Is it a known issue? (Check status page, issues)

## Network Connectivity

Test basic connectivity:

```bash
# Check DNS
nslookup api.example.com

# Test connection
curl https://api.example.com/health -v

# Check latency
ping api.example.com

# Check routing
traceroute api.example.com
```

## Authentication Issues

Verify authentication:

```bash
# Check token validity
curl -H "Authorization: Bearer <token>" https://api.example.com/users/me

# Try different token
export NEWTOKEN=$(curl -X POST https://api.example.com/auth/token \
  -d '{"api_key": "sk_live_abc123"}' | jq -r '.access_token')

# Retry with new token
curl -H "Authorization: Bearer $NEWTOKEN" https://api.example.com/users
```

## Request Debugging

Isolate issues:

```bash
# Step 1: Test with curl (isolate SDK issue)
curl https://api.example.com/users/user_123 \
  -H "Authorization: Bearer token"

# Step 2: Test with valid token (isolate auth)
curl https://api.example.com/users/user_123 \
  -H "Authorization: Bearer $(get_valid_token)"

# Step 3: Test with different user ID (isolate data issue)
curl https://api.example.com/users/user_456

# Step 4: Test simpler endpoint (isolate endpoint)
curl https://api.example.com/health
```

## Log Analysis

Search logs for issues:

```bash
# Find errors for request
logs | filter(request_id = 'req_abc123')

# Find all errors for user
logs | filter(user_id = 'user_123' AND level = 'ERROR')

# Find slow requests
logs | filter(duration_ms > 5000)

# Find recent changes
logs | filter(timestamp > now() - 1h) | group_by(service)
```

## Performance Issues

Diagnose slowness:

```bash
# Measure request time
time curl https://api.example.com/users/user_123

# Check network latency
ping -c 5 api.example.com

# Check service health
curl https://api.example.com/health

# Check database queries
db.users.find({ _id: 'user_123' }).explain('executionStats')
```

## Data Inconsistency

Verify data consistency:

```bash
# Fetch from API
curl https://api.example.com/users/user_123 | jq .

# Fetch from database (if access available)
db.users.findOne({ _id: 'user_123' })

# Compare values
# If different: cache stale, database inconsistent, or API bug
```

## Version Compatibility

Check version compatibility:

```bash
# Check SDK version
npm list @saasplatform/sdk

# Check API version (from response headers)
curl -i https://api.example.com/users | grep API-Version

# Check for deprecation warnings
curl -i https://api.example.com/users | grep Deprecation
```

## Common Issues

| Symptom | Cause | Fix |
|---------|-------|-----|
| 401 errors | Missing/invalid token | Refresh or re-authenticate |
| 403 errors | Insufficient scope | Request broader scopes |
| 404 errors | Resource doesn't exist | Verify resource ID exists |
| 429 errors | Rate limited | Implement backoff |
| 500 errors | Server error | Retry with backoff |
| Timeout | Slow service | Increase timeout, simplify query |
| Slow response | Database slow | Add indexes, optimize query |
| High error rate | Service down | Check status page, page oncall |

## Contacting Support

When reaching out to support:

1. **Include request ID**: Essential for tracing
2. **Describe issue**: What were you trying to do?
3. **Include error message**: Exact error response
4. **Share steps to reproduce**: Minimal example
5. **Include environment**: API version, SDK version, language
6. **Attach logs**: Full logs of failing requests

Example support request:

```
Subject: 404 errors on user creation

Request ID: req_xyz789
Issue: Creating users returns 404 after successful creation
Steps to reproduce:
  curl -X POST https://api.example.com/users \
    -H "Authorization: Bearer token" \
    -d '{"name": "Alice", "email": "alice@example.com"}'
  Returns: 201 Created with user_id: user_123
  
  curl https://api.example.com/users/user_123 \
  Returns: 404 Not Found
  
Environment:
  API: v2
  SDK: saasplatform/sdk-js 2.3.0
  Node: 18.0.0
  
Logs: [attached]
```

See [Error Handling](error-handling.md) and [Common Errors](common-errors.md) for detailed guidance.