API Debugging Skill

Purpose & Activation

What it does: Provides diagnostic insights for API-related issues, HTTP errors, and network debugging.

When it activates:

"API request failed"
"Why am I getting 404?"
"Debug this API call"
"HTTP status code meaning"
"API authentication error"

How it helps:

Interprets HTTP status codes
Suggests fixes for common API errors
Validates API request/response structure
Checks authentication issues
Tests API endpoints

JIT Help Available: For quick reference on common API errors and debugging commands, see: Cheat Sheet

Key Operations

Operation 1: HTTP Status Code Interpretation

User Query:

"What does status code 403 mean?" "Why am I getting 401?" "Explain this error code"

Confidence: 🟢 High (0.95)

HTTP status codes are well-defined standards
Exact keyword match: status code number
Deterministic interpretation

Skill Response:

📡 HTTP Status Code: 403 Forbidden

**Meaning:**
The server understood your request but refuses to authorize it.

**Common Causes:**
1. **Authentication missing** - No credentials provided
2. **Authorization failed** - Valid credentials but insufficient permissions
3. **IP blocked** - Your IP address is denied access
4. **API rate limit** - Too many requests (check X-RateLimit headers)
5. **Invalid API key** - Key expired or revoked

**Quick Fixes:**
1. Check authorization header: `Authorization: Bearer <token>`
2. Verify API key hasn't expired
3. Check user permissions for this endpoint
4. Review rate limit status
5. Confirm IP is whitelisted (if applicable)

**Debug Command:**
```bash
# Test with verbose output
curl -v -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/endpoint

# Check response headers
curl -I https://api.example.com/endpoint


**Why This Matters:**
- 403 vs 401 distinction is critical (authorization vs authentication)
- Misdiagnosing means wasting time on wrong fix
- Status codes reveal server-side vs client-side issues
- **Quick win:** Check authorization header format right now

**Next Step:** Test API with curl command to see full error details

### Operation 2: API Request Validation

**User Query:**
> "My API request isn't working"
> "Debug this fetch call"
> "API returns unexpected response"

**Confidence:** 🟡 Medium (0.70)
- Requires seeing actual request code
- Multiple possible failure points
- Context-dependent debugging

**Skill Response:**

🔍 API Request Debugging Checklist

1. Request Structure:

✓ Correct HTTP method? (GET/POST/PUT/DELETE)
✓ Valid URL format? (https://api.example.com/v1/resource)
✓ Headers included? (Content-Type, Authorization)
✓ Body format correct? (JSON, form-data, etc.)

2. Authentication:

✓ API key/token present in headers?
✓ Token hasn't expired?
✓ Correct authentication scheme? (Bearer, Basic, API-Key)

3. Request Body:

✓ JSON syntax valid? (use json.tool to validate)
✓ Required fields included?
✓ Data types correct? (string vs number vs boolean)

4. Network:

✓ Internet connection working?
✓ Firewall/proxy not blocking?
✓ CORS configured (if browser request)?

Debug Steps:

# 1. Test with curl first (eliminates code issues)
curl -X POST https://api.example.com/endpoint \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"key":"value"}'

# 2. Validate JSON body
echo '{"your":"json"}' | python -m json.tool

# 3. Check DNS resolution
nslookup api.example.com

# 4. Test connectivity
ping api.example.com

Common Issues:

Missing Content-Type → Server rejects request
Wrong HTTP method → 405 Method Not Allowed
CORS error → Add CORS headers or use proxy
SSL error → Certificate validation issue


**Why This Matters:**
- Systematic checklist prevents missing obvious issues
- curl eliminates language-specific bugs (tests API directly)
- 80% of API errors are client-side (your request, not their server)
- **Quick win:** Run curl command to isolate issue to code vs API

**Next Step:** Share curl output or request code for specific diagnosis

### Operation 3: API Response Parsing Issues

**User Query:**
> "API response is undefined"
> "Can't parse JSON response"
> "Response data is null"

**Confidence:** 🟢 High (0.85)
- Common parsing error patterns
- Deterministic validation steps
- Clear fix recommendations

**Skill Response:**

🔧 API Response Parsing Debug

Step 1: Check Response Status

fetch('https://api.example.com/data')
  .then(response => {
    console.log('Status:', response.status); // Check this first!
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    return response.json();
  })

Step 2: Validate Response Body

// Log raw response before parsing
fetch('https://api.example.com/data')
  .then(response => response.text()) // Don't parse yet
  .then(text => {
    console.log('Raw response:', text); // Inspect actual content
    return JSON.parse(text); // Parse manually to catch errors
  })

Common Issues:

Issue 1: Empty Response Body

Problem: response.json() fails because body is empty
Fix: Check if response.status is 204 (No Content) or 304 (Not Modified)

Issue 2: HTML Error Page (Not JSON)

Problem: API returns HTML error page instead of JSON
Symptom: "Unexpected token < in JSON"
Fix: Log response.text() to see actual HTML error

Issue 3: Wrong Content-Type

Problem: Server sends JSON but headers say text/plain
Fix: Use response.text() then JSON.parse() manually

Issue 4: Malformed JSON

Problem: Server returns invalid JSON
Fix: Validate with: echo 'RESPONSE' | python -m json.tool

Debug Command:

# Test response in terminal
curl -v https://api.example.com/endpoint 2>&1 | less

# Save response to file for inspection
curl https://api.example.com/endpoint > response.json
cat response.json | python -m json.tool


**Why This Matters:**
- "undefined" usually means successful request but wrong parsing approach
- Checking status before parsing prevents cryptic errors
- Raw response inspection reveals server-side issues (HTML errors, wrong format)
- **Quick win:** Add console.log('Status:', response.status) before parsing

**Next Step:** Log raw response to identify if it's format issue or network issue

---

## Common API Error Patterns

### Pattern 1: Authentication Errors (401/403)

401 Unauthorized → Missing or invalid credentials 403 Forbidden → Valid credentials but no permission

Fix order:

Verify credentials exist and aren't expired
Check header format: Authorization: Bearer <token>
Confirm user has required permissions
Test with API provider's example credentials


### Pattern 2: Rate Limiting (429)

429 Too Many Requests → Exceeded API rate limit

Headers to check:

X-RateLimit-Limit: Total requests allowed
X-RateLimit-Remaining: Requests left
X-RateLimit-Reset: When limit resets (Unix timestamp)

Fix:

Implement exponential backoff
Cache responses to reduce requests
Upgrade API plan if needed


### Pattern 3: Server Errors (500-599)

500 Internal Server Error → Server-side bug 502 Bad Gateway → Proxy/load balancer issue 503 Service Unavailable → Server overloaded or maintenance 504 Gateway Timeout → Upstream service too slow

Your action:

NOT your fault (server-side issue)
Check API status page
Implement retry logic with backoff
Contact API support if persistent


---

## HTTP Status Code Quick Reference

**2xx Success:**
- 200 OK - Request succeeded
- 201 Created - Resource created successfully
- 204 No Content - Success but no response body

**3xx Redirection:**
- 301 Moved Permanently - Resource moved, update URL
- 304 Not Modified - Use cached version

**4xx Client Errors (Your Problem):**
- 400 Bad Request - Invalid request syntax
- 401 Unauthorized - Authentication required
- 403 Forbidden - No permission
- 404 Not Found - Resource doesn't exist
- 405 Method Not Allowed - Wrong HTTP method
- 429 Too Many Requests - Rate limited

**5xx Server Errors (Their Problem):**
- 500 Internal Server Error - Server bug
- 502 Bad Gateway - Proxy error
- 503 Service Unavailable - Server down
- 504 Gateway Timeout - Server too slow

---

## Debugging Tools

### curl (Command Line)
```bash
# Basic GET request
curl https://api.example.com/endpoint

# POST with JSON body
curl -X POST https://api.example.com/endpoint \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}'

# With authentication
curl -H "Authorization: Bearer TOKEN" https://api.example.com/endpoint

# Verbose output (see full request/response)
curl -v https://api.example.com/endpoint

# Save response to file
curl -o response.json https://api.example.com/endpoint

Browser DevTools

Network tab → Click request → Check:
- Status code
- Request headers (Authorization, Content-Type)
- Response headers
- Response body (Preview or Response tab)
- Timing (to identify slow requests)

Postman/Insomnia

Benefits:
- Visual interface for API testing
- Save requests for reuse
- Environment variables for tokens
- Auto-generate code snippets

Token Efficiency Analysis

Without This Skill (900 tokens per debug session)

Process:

User: "Why 403 error?" (50 tokens)
Claude: "Let me check HTTP standards..." (150 tokens)
Explain status codes (200 tokens)
Ask for request details (100 tokens)
User provides details (150 tokens)
Diagnose specific issue (250 tokens)

Total: ~900 tokens

With This Skill (350 tokens per debug session)

Process:

User: "Why 403 error?" (50 tokens)
Skill activates with pre-compiled knowledge (100 tokens)
Provides interpretation + fixes immediately (200 tokens)

Total: ~350 tokens

Savings: 550 tokens per debug session (61% reduction)

Frequency: Developers debug APIs 5-10 times per week

Weekly: 2,750-5,500 tokens saved
Monthly: 11,000-22,000 tokens saved (~$0.33-$0.66/month)

Best Practices

For Users

Test with curl first - Eliminates code-specific issues
Log raw responses - Before parsing, inspect actual content
Check status codes - Before assuming success
Read API docs - Authentication, rate limits, error codes
Use API status pages - Check if service is down

For Claude (Using This Skill)

Ask for status code - First question in debugging
Provide curl examples - Universal testing method
Distinguish 4xx vs 5xx - Client vs server responsibility
Link to API docs - When available
Suggest logging - Before parsing

api-debugging