gh-jeremylongshore-claude-code-plugins-plus-plugins-mcp-conversational-api-debugger/commands/debug-api.md

---
description: Debug API failures using OpenAPI specs and HTTP logs
---

# Debug API Failures

Systematically debug REST API failures by analyzing OpenAPI specifications and HTTP request/response logs.

## Workflow

When the user requests API debugging, follow this comprehensive approach:

### Step 1: Load API Documentation

```
Use load_openapi to parse the OpenAPI spec:
- Accepts JSON or YAML format
- Extracts all endpoints, parameters, and expected responses
- Identifies authentication requirements
- Captures base URLs and server information

Example:
load_openapi({
  filePath: "/path/to/openapi.yaml",
  name: "my-api"
})
```

### Step 2: Ingest HTTP Logs

```
Use ingest_logs to import request/response data:
- Supports HAR (HTTP Archive) format from browser DevTools
- Accepts direct log arrays
- Automatically categorizes successful vs failed requests
- Calculates status code and method distributions

Example (HAR file):
ingest_logs({
  filePath: "/path/to/requests.har",
  format: "har"
})

Example (direct logs):
ingest_logs({
  logs: [
    {
      timestamp: "2025-10-10T12:00:00Z",
      method: "POST",
      url: "https://api.example.com/users",
      statusCode: 400,
      requestBody: { "name": "John" },
      responseBody: { "error": "Missing required field: email" }
    }
  ]
})
```

### Step 3: Analyze Failures

```
Use explain_failure to understand why requests failed:
- Identifies root causes based on HTTP status codes
- Compares actual behavior with OpenAPI spec expectations
- Suggests specific fixes
- Assesses severity (critical, high, medium, low)

Example:
explain_failure({
  logIndex: 0,  // Index from ingest_logs
  specName: "my-api"  // Compare against loaded spec
})
```

### Step 4: Generate Reproducible Tests

```
Use make_repro to create cURL commands:
- Generates executable cURL command
- Includes alternative formats (HTTPie, JavaScript fetch)
- Useful for documentation, bug reports, and testing

Example:
make_repro({
  logIndex: 0,
  includeHeaders: true,
  pretty: true  // Format for readability
})
```

## Common Debugging Scenarios

### Scenario 1: 400 Bad Request

1. **Load spec** to see expected request format
2. **Ingest logs** containing the failure
3. **Explain failure** to identify validation errors
4. **Make repro** to generate test command
5. **Fix request** based on schema requirements
6. **Test** using generated cURL command

### Scenario 2: 401 Unauthorized

1. **Load spec** to check authentication requirements
2. **Explain failure** on 401 response
3. **Verify** authentication headers in request
4. **Check** token expiration or permissions
5. **Make repro** with corrected auth headers

### Scenario 3: 500 Internal Server Error

1. **Ingest logs** to find pattern of 500 errors
2. **Explain failure** to assess criticality
3. **Make repro** for server team to reproduce
4. **Check** request payload for edge cases
5. **Monitor** server logs (not in scope of this tool)

### Scenario 4: Performance Issues

1. **Ingest logs** with duration data
2. **Analyze** distribution of response times
3. **Identify** slow endpoints
4. **Make repro** for performance testing

## Analysis Output

The debugging workflow produces:

### From explain_failure:
- **Severity**: critical | high | medium | low
- **Possible Causes**: List of likely root causes
- **Suggested Fixes**: Actionable remediation steps
- **Matching Endpoint**: Comparison with OpenAPI spec
- **Details**: Request/response bodies for inspection

### From make_repro:
- **cURL Command**: Copy-paste ready command
- **HTTPie Alternative**: Shorter syntax for quick tests
- **JavaScript fetch**: For integration into automated tests
- **Metadata**: Method, URL, headers, body presence

## Best Practices

1. **Always load the OpenAPI spec first** - Provides context for failure analysis
2. **Use HAR files** when possible - Most complete log format
3. **Include request/response bodies** - Critical for validation errors
4. **Compare with spec** - Catches mismatches between docs and implementation
5. **Generate repro commands** - Makes bug reports actionable
6. **Test fixes immediately** - Use generated cURL to verify

## Tips

- Export HAR from browser DevTools (Network tab → Right-click → Save as HAR)
- Use `pretty: true` for readable cURL commands (good for docs)
- Use `pretty: false` for one-liner cURL (good for scripts)
- Check response headers for hints (X-RateLimit-*, Retry-After, etc.)
- Look for patterns in multiple failures (same endpoint, same error)

## Example Usage

```
User: "My API is returning 400 errors, help me debug"

You:
1. First, do you have an OpenAPI spec? If yes, I'll load it.
2. How are you capturing HTTP logs? (HAR file, JSON logs, manual entry?)
3. Let me analyze the failures and suggest fixes.

[After receiving spec and logs]

I've loaded your API spec and found 5 failed requests:
- 3x POST /users → 400 (Missing required field: email)
- 2x GET /users/{id} → 404 (Invalid user ID format)

Let me explain the first failure...
[Uses explain_failure]

Here's a working cURL command to test the fix:
[Uses make_repro]
```

## Notes

- This tool focuses on client-side debugging (requests/responses)
- Server-side logs and profiling are out of scope
- For complex API issues, combine with other debugging tools
- Keep OpenAPI specs up-to-date for accurate analysis