René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Improve rate limit error messages for AI agents","articleBody":"### Summary\n\nWhen the GitHub API returns a rate limit error, the message surfaced to the AI model as a tool result is either missing the retry duration entirely, or buries it inside a noisy raw HTTP string. This makes it hard for agents to know how long to wait before retrying.\n\nAll tool errors flow through `NewGitHubAPIErrorResponse` in `pkg/errors/error.go`, which formats the tool result as:\n\n```\n\u003ctool message\u003e: \u003cerr.Error()\u003e\n```\n\nFor a **primary rate limit** (`RateLimitError`), the agent sees:\n\n```\nsearch code: GET https://api.github.com/search/code: 403 API rate limit exceeded for user ID 12345. [rate reset in 47s]\n```\n\nThe reset time is present but buried inside a raw HTTP method + URL + status string.\n\nFor a **secondary (abuse) rate limit** (`AbuseRateLimitError`), the agent sees:\n\n```\nsearch code: GET https://api.github.com/search/code: 403 You have exceeded a secondary rate limit and have been temporarily blocked from content creation. Please retry your request again later.\n```\n\nThe `Retry-After` duration is **completely absent** — it is populated in the struct from the HTTP header but dropped by `AbuseRateLimitError.Error()` (tracked upstream in google/go-github#4180).\n\n### Suggested fix\n\nIn `NewGitHubAPIErrorResponse`, use `errors.As` to detect rate limit error types and return a clean, agent-friendly message:\n\n```go\nfunc NewGitHubAPIErrorResponse(ctx context.Context, message string, resp *github.Response, err error) *mcp.CallToolResult {\n    apiErr := newGitHubAPIError(message, resp, err)\n    if ctx != nil {\n        _, _ = addGitHubAPIErrorToContext(ctx, apiErr)\n    }\n\n    var rateLimitErr *github.RateLimitError\n    if errors.As(err, \u0026rateLimitErr) {\n        retryIn := time.Until(rateLimitErr.Rate.Reset.Time).Round(time.Second)\n        return utils.NewToolResultError(fmt.Sprintf(\n            \"%s: GitHub API rate limit exceeded. Retry after %v.\",\n            message, retryIn))\n    }\n\n    var abuseErr *github.AbuseRateLimitError\n    if errors.As(err, \u0026abuseErr) {\n        if abuseErr.RetryAfter != nil {\n            return utils.NewToolResultError(fmt.Sprintf(\n                \"%s: GitHub secondary rate limit exceeded. Retry after %v.\",\n                message, abuseErr.RetryAfter.Round(time.Second)))\n        }\n        return utils.NewToolResultError(fmt.Sprintf(\n            \"%s: GitHub secondary rate limit exceeded. Wait before retrying.\",\n            message))\n    }\n\n    return utils.NewToolResultErrorFromErr(message, err)\n}\n```\n\nThis gives the agent clear, actionable output:\n\n```\nsearch code: GitHub API rate limit exceeded. Retry after 47s.\n```\n\n```\nsearch code: GitHub secondary rate limit exceeded. Retry after 60s.\n```\n\n\u003e **Note:** This fix is independent of google/go-github#4180 — it reads `RetryAfter` directly from the struct rather than relying on `.Error()`. The go-github fix benefits all other callers of the library.\n\n\u003e [!NOTE]\n\u003e This issue was drafted with the assistance of GitHub Copilot.\n","author":{"url":"https://github.com/danmoseley","@type":"Person","name":"danmoseley"},"datePublished":"2026-04-25T18:54:58.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/2385/github-mcp-server/issues/2385"}