Problem

The remote server's error_categorizer.go uses context to extract GitHub API errors for observability metrics. However, when API calls succeed but return unexpected HTTP status codes (e.g., 404, 422, 500), the errors were returned via utils.NewToolResultError which bypasses the context-based error tracking.

This resulted in 100% tool call success rates in observability even when errors occurred.

Root Cause

There are three categories of errors in the tool handlers:

1. Parameter validation errors (e.g., RequiredParam failures) - These correctly use utils.NewToolResultError as they are user input errors, not GitHub API errors.

2. GitHub API client errors (when err != nil after API call) - These mostly use ghErrors.NewGitHubAPIErrorResponse and are tracked correctly.

3. HTTP status code errors (when API succeeds but returns non-2xx) - These were using utils.NewToolResultError and were NOT being tracked.

Solution

Add a new helper function NewGitHubAPIStatusErrorResponse that:

1. Creates a synthetic error from the status code and response body
2. Records the error in context via NewGitHubAPIErrorResponse
3. Returns the MCP error result to the client

Then systematically updated all tool files to use this new pattern.

Changes

New Function in pkg/errors/error.go

// NewGitHubAPIStatusErrorResponse handles cases where the API call succeeds (err == nil)
// but returns an unexpected HTTP status code. It creates a synthetic error from the
// status code and response body, then records it in context for observability tracking.
func NewGitHubAPIStatusErrorResponse(ctx context.Context, message string, resp *github.Response, body []byte) *mcp.CallToolResult {
    err := fmt.Errorf("unexpected status %d: %s", resp.StatusCode, string(body))
    return NewGitHubAPIErrorResponse(ctx, message, resp, err)
}

Files Updated

Relation to Existing PRs

This PR addresses the bulk of the error tracking issue that PRs #1566 and #1570 are also addressing:

• Add API Error annotations to GitHub issue errors #1566 adds NewGitHubGraphQLErrorToCtx and fixes a few issues.go errors
• Add raw client error annotation and annotate GetFileContents #1570 adds GitHubRawAPIError type for raw client errors and fixes GetFileContents

This PR focuses on the ~69 HTTP status code error paths across all tool files that were not being tracked. After this PR merges:

• Add API Error annotations to GitHub issue errors #1566 may still be useful for its GraphQL helper
• Add raw client error annotation and annotate GetFileContents #1570 is still useful for raw client error tracking

Testing

• ✅ All existing tests pass
• ✅ Added test for NewGitHubAPIStatusErrorResponse
• ✅ Lint passes with 0 issues

Notes

• Parameter validation errors continue to use utils.NewToolResultError - they are user input errors, not API errors
• Internal I/O errors (e.g., io.ReadAll failures) continue to use utils.NewToolResultErrorFromErr - they are not GitHub API errors
• Only errors where we have a resp (GitHub Response) and ctx are tracked