feat: add timeout, retry, and rate-limit resilience to Hevy API client (#425)

* fix: add timeout and bounded retries for hevy api client

* test: cover Hevy client retry edge cases

* fix: bound retry-after delays and retry-exhausted classification

* style: format hevy client kubb tests

* test: cover retry-aware error messages

---------

Co-authored-by: CharlieHelps <charlie@charlielabs.ai>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Author: 3 people

.changeset/curly-pears-smile.md

@@ -0,0 +1,8 @@
+---
+"hevy-mcp": patch
+---
+
+Add resilient Hevy API request handling with configurable timeout,
+bounded retries for transient GET failures, Retry-After support for
+429 responses, and clearer user-facing rate-limit/transient error
+messages.

.env.sample

@@ -1,4 +1,6 @@
 HEVY_API_KEY=HEVY_KEY
+# Optional timeout for Hevy API requests in milliseconds (default: 30000)
+# HEVY_MCP_API_TIMEOUT=30000
 
 # Sentry Configuration (optional - for source map uploads during build)
 # SENTRY_AUTH_TOKEN=your_sentry_auth_token_here

README.md

@@ -175,9 +175,14 @@ Supply your Hevy API key via the `HEVY_API_KEY` environment variable (in
 > `hevy-api-key=...`) are still accepted for backward compatibility, but are
 > deprecated and insecure. Use `HEVY_API_KEY` instead.
 
+Set `HEVY_MCP_API_TIMEOUT` to override the default 30-second Hevy API request
+timeout. Its value is in milliseconds.
+
 ```env
 # Example .env
 HEVY_API_KEY=your_hevy_api_key_here
+# Optional: customize Hevy API request timeout (milliseconds)
+HEVY_MCP_API_TIMEOUT=30000
 ```
 
 ### 🧠 Exercise Template Cache Behavior

src/utils/error-handler.test.ts

@@ -227,7 +227,8 @@ describe("Error Handler", () => {
 			},
 			{
 				status: 429,
-				expectedMessage: "Rate limited by Hevy. Please wait and retry.",
+				expectedMessage:
+					"Rate limited by Hevy (HTTP 429). Please wait and retry your request.",
 			},
 			{
 				status: 503,
@@ -264,6 +265,97 @@ describe("Error Handler", () => {
 			},
 		);
 
+		it("includes Retry-After in 429 error messages", () => {
+			const response = createErrorResponse({
+				isAxiosError: true,
+				response: {
+					headers: { "retry-after": "12" },
+					status: 429,
+				},
+			});
+
+			expect(response.content[0].text).toBe(
+				"Error: Rate limited by Hevy (HTTP 429). " +
+					"Please wait about 12 seconds before retrying.",
+			);
+		});
+
+		it("reads Retry-After from header getters with array values", () => {
+			const response = createErrorResponse({
+				isAxiosError: true,
+				response: {
+					headers: { get: () => [4] },
+					status: 429,
+				},
+			});
+
+			expect(response.content[0].text).toBe(
+				"Error: Rate limited by Hevy (HTTP 429). " +
+					"Please wait about 4 seconds before retrying.",
+			);
+		});
+
+		it("includes HTTP-date Retry-After values in 429 error messages", () => {
+			const now = Date.parse("2026-07-09T19:40:00Z");
+			vi.spyOn(Date, "now").mockReturnValue(now);
+			const response = createErrorResponse({
+				isAxiosError: true,
+				response: {
+					headers: {
+						"retry-after": new Date(now + 2_000).toUTCString(),
+					},
+					status: 429,
+				},
+			});
+
+			expect(response.content[0].text).toBe(
+				"Error: Rate limited by Hevy (HTTP 429). " +
+					"Please wait about 2 seconds before retrying.",
+			);
+		});
+
+		it("falls back to the generic message for invalid Retry-After values", () => {
+			const response = createErrorResponse({
+				isAxiosError: true,
+				response: {
+					headers: { "retry-after": "not-a-date" },
+					status: 429,
+				},
+			});
+
+			expect(response.content[0].text).toBe(
+				"Error: Rate limited by Hevy (HTTP 429). " +
+					"Please wait and retry your request.",
+			);
+		});
+
+		it("prioritizes exhausted retry errors over status mappings", () => {
+			const response = createErrorResponse({
+				hevyRetryCount: 2,
+				hevyRetryExhausted: true,
+				isAxiosError: true,
+				response: { status: 503 },
+			});
+
+			expect(response.content[0].text).toBe(
+				"Error: Unable to complete the request after 3 attempts " +
+					"to the Hevy API due to transient failures. Please try again shortly.",
+			);
+		});
+
+		it("describes exhausted retry errors without a retry count", () => {
+			const response = createErrorResponse({
+				hevyRetryExhausted: true,
+				isAxiosError: true,
+				response: { status: 503 },
+			});
+
+			expect(response.content[0].text).toBe(
+				"Error: Unable to complete the request after multiple attempts " +
+					"to the Hevy API due to transient failures. Please try again shortly.",
+			);
+		});
+
 		it("uses raw axios string data when no Hevy status mapping exists", () => {
 			const response = createErrorResponse(
 				createMockAxiosError(400, "plain upstream message"),

src/utils/error-handler.ts

@@ -22,12 +22,130 @@ export interface ErrorResponse {
  */
 export enum ErrorType {
 	API_ERROR = "API_ERROR",
+	RATE_LIMIT = "RATE_LIMIT",
 	VALIDATION_ERROR = "VALIDATION_ERROR",
 	NOT_FOUND = "NOT_FOUND",
 	NETWORK_ERROR = "NETWORK_ERROR",
 	UNKNOWN_ERROR = "UNKNOWN_ERROR",
 }
 
+type RetryAwareError = {
+	hevyRetryCount?: number;
+	hevyRetryExhausted?: boolean;
+};
+
+function normalizeHeaderValue(value: unknown): string | undefined {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		return trimmed.length > 0 ? trimmed : undefined;
+	}
+
+	if (typeof value === "number" && Number.isFinite(value)) {
+		return String(value);
+	}
+
+	if (Array.isArray(value) && value.length > 0) {
+		return normalizeHeaderValue(value[0]);
+	}
+
+	return undefined;
+}
+
+function getHeaderValue(headers: unknown, key: string): string | undefined {
+	if (!headers || typeof headers !== "object") {
+		return undefined;
+	}
+
+	if (
+		"get" in headers &&
+		typeof (headers as { get?: unknown }).get === "function"
+	) {
+		const value = (headers as { get: (headerName: string) => unknown }).get(
+			key,
+		);
+		return normalizeHeaderValue(value);
+	}
+
+	const headerRecord = headers as Record<string, unknown>;
+	return normalizeHeaderValue(
+		headerRecord[key] ??
+			headerRecord[key.toLowerCase()] ??
+			headerRecord[key.toUpperCase()],
+	);
+}
+
+function formatSecondsLabel(seconds: number): string {
+	const roundedSeconds = Math.max(0, Math.round(seconds));
+	const suffix = roundedSeconds === 1 ? "" : "s";
+	return `${roundedSeconds} second${suffix}`;
+}
+
+function getRateLimitMessage(error: unknown): string {
+	if (!isAxiosError(error)) {
+		return "Rate limited by Hevy. Please wait and retry.";
+	}
+
+	const retryAfterHeader = getHeaderValue(
+		error.response?.headers,
+		"retry-after",
+	);
+	if (!retryAfterHeader) {
+		return "Rate limited by Hevy (HTTP 429). Please wait and retry your request.";
+	}
+
+	const seconds = Number(retryAfterHeader);
+	if (Number.isFinite(seconds) && seconds >= 0) {
+		return `Rate limited by Hevy (HTTP 429). Please wait about ${formatSecondsLabel(seconds)} before retrying.`;
+	}
+
+	const retryAtMillis = Date.parse(retryAfterHeader);
+	if (!Number.isNaN(retryAtMillis)) {
+		const secondsUntilRetry = Math.ceil(
+			Math.max(0, retryAtMillis - Date.now()) / 1000,
+		);
+		return `Rate limited by Hevy (HTTP 429). Please wait about ${formatSecondsLabel(secondsUntilRetry)} before retrying.`;
+	}
+
+	return "Rate limited by Hevy (HTTP 429). Please wait and retry your request.";
+}
+
+function isRetryExhaustedError(error: unknown): boolean {
+	return (
+		!!error &&
+		typeof error === "object" &&
+		(error as RetryAwareError).hevyRetryExhausted === true
+	);
+}
+
+function getRetryExhaustedMessage(error: unknown): string {
+	const retryCount =
+		typeof error === "object" && error !== null
+			? (error as RetryAwareError).hevyRetryCount
+			: undefined;
+	const attemptCount =
+		typeof retryCount === "number" && Number.isFinite(retryCount)
+			? retryCount + 1
+			: undefined;
+
+	if (attemptCount) {
+		return `Unable to complete the request after ${attemptCount} attempts to the Hevy API due to transient failures. Please try again shortly.`;
+	}
+
+	return "Unable to complete the request after multiple attempts to the Hevy API due to transient failures. Please try again shortly.";
+}
+
+function getUserFacingMessage(error: unknown, defaultMessage: string): string {
+	if (isRetryExhaustedError(error)) {
+		return getRetryExhaustedMessage(error);
+	}
+
+	if (isAxiosError(error) && error.response?.status === 429) {
+		return getRateLimitMessage(error);
+	}
+
+	return defaultMessage;
+}
+
 /**
  * Enhanced error response with type categorization
  */
@@ -79,6 +197,8 @@ export function createErrorResponse(
 		errorMessage = stringifyErrorData(axiosErrorContext.data);
 	}
 
+	errorMessage = getUserFacingMessage(error, errorMessage);
+
 	// Extract error code if available (for logging purposes)
 	const errorCode =
 		error instanceof Error && "code" in error
@@ -210,6 +330,14 @@ function stringifyErrorData(data: unknown): string {
  * Determine the type of error based on error characteristics
  */
 function determineErrorType(error: unknown, message: string): ErrorType {
+	if (isRetryExhaustedError(error)) {
+		return ErrorType.NETWORK_ERROR;
+	}
+
+	if (isAxiosError(error) && error.response?.status === 429) {
+		return ErrorType.RATE_LIMIT;
+	}
+
 	const messageLower = message.toLowerCase();
 	const nameLower = error instanceof Error ? error.name.toLowerCase() : "";