Improve error message extraction from Mapbox API responses (#102)

* Improve error message extraction from Mapbox API responses

Add getErrorMessage() helper method to MapboxApiBasedTool base class
that extracts the 'message' field from JSON error responses when
available, falling back to status text otherwise.

Updated all 10 API-based tools to use this helper:
- DirectionsTool
- SearchAndGeocodeTool
- OptimizationTool
- MapMatchingTool
- MatrixTool
- ReverseGeocodeTool
- CategorySearchTool
- StaticMapImageTool
- IsochroneTool
- CategoryListTool

Benefits:
- More informative error messages (e.g., "Not Authorized - Invalid Token" vs "Unauthorized")
- Consistent error handling across all tools
- Centralized error parsing logic
- Simplified code (reduced from 20+ lines to 5 lines in some tools)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

* Include HTTP status code in error messages

---------

Co-authored-by: Claude Sonnet 4.5 <[email protected]>

Author: mattpodwysocki

src/tools/MapboxApiBasedTool.ts

@@ -55,6 +55,26 @@ export abstract class MapboxApiBasedTool<
     return parts.every((part) => part.length > 0);
   }
 
+  /**
+   * Extracts error message from Mapbox API response.
+   * If the response contains a JSON body with a 'message' field, returns that.
+   * Otherwise falls back to the response status text.
+   * @param response The HTTP response object
+   * @returns The error message string in format "statusCode: message"
+   */
+  protected async getErrorMessage(response: Response): Promise<string> {
+    try {
+      const errorBody = await response.text();
+      const errorJson = JSON.parse(errorBody);
+      if (errorJson.message) {
+        return `${response.status}: ${errorJson.message}`;
+      }
+    } catch {
+      // If parsing fails, fall back to status text
+    }
+    return `${response.status}: ${response.statusText}`;
+  }
+
   /**
    * Validates and runs the tool logic.
    */

src/tools/category-list-tool/CategoryListTool.ts

@@ -71,11 +71,12 @@ export class CategoryListTool extends MapboxApiBasedTool<
     });
 
     if (!response.ok) {
+      const errorMessage = await this.getErrorMessage(response);
       return {
         content: [
           {
             type: 'text',
-            text: `Mapbox API request failed: ${response.status} ${response.statusText}`
+            text: `Category List API error: ${errorMessage}`
           }
         ],
         isError: true

src/tools/category-search-tool/CategorySearchTool.ts

@@ -149,11 +149,12 @@ export class CategorySearchTool extends MapboxApiBasedTool<
     const response = await this.httpRequest(url.toString());
 
     if (!response.ok) {
+      const errorMessage = await this.getErrorMessage(response);
       return {
         content: [
           {
             type: 'text',
-            text: `Failed to search category: ${response.status} ${response.statusText}`
+            text: `Category Search API error: ${errorMessage}`
           }
         ],
         isError: true

src/tools/directions-tool/DirectionsTool.ts

@@ -241,11 +241,12 @@ export class DirectionsTool extends MapboxApiBasedTool<
     const response = await this.httpRequest(url);
 
     if (!response.ok) {
+      const errorMessage = await this.getErrorMessage(response);
       return {
         content: [
           {
             type: 'text',
-            text: `Request failed with status ${response.status}: ${response.statusText}`
+            text: `Directions API error: ${errorMessage}`
           }
         ],
         isError: true

src/tools/isochrone-tool/IsochroneTool.ts

@@ -136,11 +136,12 @@ export class IsochroneTool extends MapboxApiBasedTool<
     const response = await this.httpRequest(url);
 
     if (!response.ok) {
+      const errorMessage = await this.getErrorMessage(response);
       return {
         content: [
           {
             type: 'text',
-            text: `Failed to calculate isochrones: ${response.status} ${response.statusText}`
+            text: `Isochrone API error: ${errorMessage}`
           }
         ],
         isError: true

src/tools/map-matching-tool/MapMatchingTool.ts

@@ -105,22 +105,14 @@ export class MapMatchingTool extends MapboxApiBasedTool<
     const response = await this.httpRequest(url);
 
     if (!response.ok) {
-      const errorText = await response.text();
-      let errorMessage = `Request failed with status ${response.status}: ${response.statusText}`;
-
-      try {
-        const errorJson = JSON.parse(errorText);
-        if (errorJson.message) {
-          errorMessage = `${errorMessage} - ${errorJson.message}`;
-        }
-      } catch {
-        if (errorText) {
-          errorMessage = `${errorMessage} - ${errorText}`;
-        }
-      }
-
+      const errorMessage = await this.getErrorMessage(response);
       return {
-        content: [{ type: 'text', text: errorMessage }],
+        content: [
+          {
+            type: 'text',
+            text: `Map Matching API error: ${errorMessage}`
+          }
+        ],
         isError: true
       };
     }

src/tools/matrix-tool/MatrixTool.ts

@@ -282,11 +282,12 @@ export class MatrixTool extends MapboxApiBasedTool<
     const response = await this.httpRequest(url);
 
     if (!response.ok) {
+      const errorMessage = await this.getErrorMessage(response);
       return {
         content: [
           {
             type: 'text',
-            text: `Request failed with status ${response.status}: ${response.statusText}`
+            text: `Matrix API error: ${errorMessage}`
           }
         ],
         isError: true

src/tools/optimization-tool/OptimizationTool.ts

@@ -101,27 +101,20 @@ export class OptimizationTool extends MapboxApiBasedTool<
       const response = await this.httpRequest(url);
 
       if (!response.ok) {
-        const errorText = await response.text();
-        let errorMessage = `Request failed with status ${response.status}: ${response.statusText}`;
-
-        try {
-          const errorJson = JSON.parse(errorText);
-          if (errorJson.message) {
-            errorMessage = `${errorMessage} - ${errorJson.message}`;
-          }
-        } catch {
-          if (errorText) {
-            errorMessage = `${errorMessage} - ${errorText}`;
-          }
-        }
+        const errorMessage = await this.getErrorMessage(response);
 
         toolContext.span.setStatus({
           code: SpanStatusCode.ERROR,
           message: errorMessage
         });
 
         return {
-          content: [{ type: 'text' as const, text: errorMessage }],
+          content: [
+            {
+              type: 'text' as const,
+              text: `Optimization API error: ${errorMessage}`
+            }
+          ],
           isError: true
         };
       }

src/tools/reverse-geocode-tool/ReverseGeocodeTool.ts

@@ -136,11 +136,12 @@ export class ReverseGeocodeTool extends MapboxApiBasedTool<
     const response = await this.httpRequest(url.toString());
 
     if (!response.ok) {
+      const errorMessage = await this.getErrorMessage(response);
       return {
         content: [
           {
             type: 'text',
-            text: `Failed to reverse geocode: ${response.status} ${response.statusText}`
+            text: `Reverse Geocode API error: ${errorMessage}`
           }
         ],
         isError: true

src/tools/search-and-geocode-tool/SearchAndGeocodeTool.ts

@@ -175,16 +175,16 @@ export class SearchAndGeocodeTool extends MapboxApiBasedTool<
     const response = await this.httpRequest(url.toString());
 
     if (!response.ok) {
-      const errorBody = await response.text();
+      const errorMessage = await this.getErrorMessage(response);
       this.log(
         'error',
-        `SearchAndGeocodeTool: API Error - Status: ${response.status}, Body: ${errorBody}`
+        `SearchAndGeocodeTool: API Error - Status: ${response.status}, Message: ${errorMessage}`
       );
       return {
         content: [
           {
             type: 'text',
-            text: `Failed to search: ${response.status} ${response.statusText}`
+            text: `Search API error: ${errorMessage}`
           }
         ],
         isError: true